diff --git a/.ciagent/ARCHITECTURE.md b/.ciagent/ARCHITECTURE.md index 5f43d2e..9635a81 100644 --- a/.ciagent/ARCHITECTURE.md +++ b/.ciagent/ARCHITECTURE.md @@ -570,4 +570,93 @@ emulator + live-AWS terraform init/validate/plan. 7. CloudFront OAC + WAF deprecated arg names (AWS provider v5): `signing_behavior`, `signing_protocol`, `origin_access_control_id`, `s3_origin_config.origin_access_identity`, `origin_id`, `rule` - (singular), `scope=CLOUDFRONT` (uppercase). \ No newline at end of file + (singular), `scope=CLOUDFRONT` (uppercase). + +## v1.11 Addendum — Stateless Adapter + Pipeline-Driven Lifecycle Testing + +**Stateless adapter (D-098).** `adapters/terraform/adapter.py` rewritten +from a 918-line monolith (3 constant tables `TYPE_MAP`/`INPUT_MAP`/ +`OUTPUT_MAP`, 39 type-specific branches) to a ~80-line stateless assembler. +Each L1 module ships a real `terraform/` module dir +(`versions.tf`/`variables.tf`/`locals.tf`/`main.tf`/`outputs.tf`) owning +its resource shape, nested blocks, and defaults. The adapter reads the +registry, emits a root `main.tf` instantiating each L1 as +`module "x" { source = "..." }` with resolved inputs and wired refs. + +**Terraform owns lifecycle (D-101).** `scripts/run_platform.sh` gains +`--apply` and `--destroy` modes. Python never runs terraform. +`scripts/verify_deploy_microservice.py` is deleted. + +**Pipeline-driven testing (D-102).** A `modules-lifecycle` pipeline +(Gitea + GitHub, byte-identical) matrix-runs each L1 module's +`examples/{simple,complex}.yml` contracts through apply→modify→destroy +against live AWS. No per-module Python/pytest. The "test" = the pipeline +cell going green. + +**Single platform VPC (D-105).** `terraform/platform/main.tf` owns ONE +VPC; the microservice composition references it via +`terraform_remote_state` (data source). State keys are deterministic and +env-aware (`spike/{contract.id}/{contract.environment}/terraform.tfstate`). + +**ACDL_LIFECYCLE_MODE (v1.12, REQ-134).** The lifecycle pipeline defaults +to plan-only (fast, no AWS mutation, no cost). A CI variable +`ACDL_LIFECYCLE_MODE` (default `plan`) overrides to `full` for the real +apply→modify→destroy. + +## v1.12 Addendum — Presentation Refinement + CAP-013 Fix + +**CAP-013 adapter dedup fix (REQ-129).** Multi-resource L1s (ecs-service, +alb) with stack outputs + cross-module refs now dedup to ONE module block +named by the composition child id, with expanded sub-ids rewritten via +`id_remap`. `terraform validate` succeeds for the microservice stack. + +**CAP-017/018 probe fixes (REQ-130).** CAP-017's probe no longer requires +`locals.tf` for modules that legitimately omit it. CAP-018's probe +instantiates `LocalLambdaStub` with the required `outbox` arg. + +## v1.13 Addendum — Presentation Polish + Config Schema Migration + +**Config.json schema migration (v1.13.1).** Regenerated +`.ciagent/config.json` to the updated CIAgent v2 config structure (drop +removed fields, migrate `gitea`→`release.gitea`, add +`secrets`/`ship`/`backend`/`ideation`/`personas`/`logging`/`telemetry` +sections). + +**Presentation polish (v1.13.0, v1.13.2).** Action headlines, story-arc +restructure, larger fonts, 6 new mermaid diagrams, badge cleanup, +platform-architecture diagram. Docs-only NFR patches. + +## v1.14 Addendum — NFR Refinement (bug fixes, security, stubs, tests, docs) + +**Bug fixes (Wave 1, P1-P6).** Adapter dedup rejects unregistered modules +with ValueError (P1). Static-assets composition wires cloudfront inputs +(P2). L2 lifecycle scripts document remote-state design (P3). Regression +gate adds `terraform fmt -check` syntax probe (P4). Adapter dedup-merge + +remote-state-key unit tests (P5). ALB target group name_prefix derives +from var.name (P6). + +**Security (Wave 2, P7-P12).** 6 swallowed-error sites narrowed to +specific exceptions (P7). Account ID externalized to +`ACDL_AWS_ACCOUNT_ID` env (P8). IAM policy scoped to `acdl-*` ARNs (P9). +Contract ingestor validates contractId/environment/error (P10). Environment +schema adds `additionalProperties: false` + format validation (P11). +`.gitignore` credential-pattern catch-all (P12). + +**Stub/test/CI/hygiene (Wave 3, P13-P17).** Kyverno `--kube-version` flag +removed (P13, G-103). Orphan artifacts + dead config cleaned (P14). 7 +untested scripts gain test coverage (P15). Gitea workflow parity +documented + script `set` flags fixed (P16). Config.json persona + +branching strategy + ollama-cloud aligned (P17). + +**Standards/docs/VPC (Wave 4, P18-P20).** STANDARDS.md reconciled (P18). +Documentation synced: ARCHITECTURE.md addenda, stale `@v1.6-1.9` → `@v1.13`, +GRILL G-005/G-008 resolved, COST.md window extended, D-083 deferral +recorded (P19). Platform VPC CIDR parameterized + data-driven subnet +count (P20). + +**D-083 deferral (explicit).** The audit ledger build-out (S3 Object Lock ++ JWS detached signatures + SQS DLQ + async worker + daily checkpoints) +remains deferred (D-096, v1.14). The hash-chain + DynamoDB outbox is the +v1.14 audit record. JWS per-event authenticity is not implemented; a +forged event is only detectable by re-reading the whole chain. The +deferral is documented here explicitly per the v1.14 grill (E-001). \ No newline at end of file diff --git a/.ciagent/COST.md b/.ciagent/COST.md index 11d3e5b..64537d0 100644 --- a/.ciagent/COST.md +++ b/.ciagent/COST.md @@ -1,8 +1,8 @@ -# ACDL AWS Cost Report (v1.0 → v1.10) +# ACDL AWS Cost Report (v1.0 → v1.14) -> **Query date:** 2026-07-28 +> **Query date:** 2026-07-29 (updated v1.14 P19) > **Source:** AWS Cost Explorer (`ce:GetCostAndUsage`) -> **Window:** 2026-07-21 → 2026-07-28 (v1.0 ship → v1.10 complete) +> **Window:** 2026-07-21 → 2026-07-29 (v1.0 ship → v1.14 active) > **Account:** 581513795199 (us-east-1) > **Closes:** G-008 (no cost documentation despite live AWS resources) diff --git a/.ciagent/GRILL.md b/.ciagent/GRILL.md index 44e530b..0002018 100644 --- a/.ciagent/GRILL.md +++ b/.ciagent/GRILL.md @@ -6,7 +6,13 @@ Two escalations must be resolved before the leadership pitch: - **G-005 (risks):** 6 cloud capabilities (CAP-017..022) are deploy-unverified. + **RESOLVED (v1.11):** CAP-017..022 are now Verified live-aws via the + modules-lifecycle pipeline (apply/modify/destroy exit 0). The IAM-drift + framing is removed. See CAPABILITY_INVENTORY.md. - **G-008 (budget):** No cost documentation exists despite live AWS resources. + **RESOLVED (v1.11):** COST.md now exists, documenting the v1.0→v1.10 spend + window + the v1.11 cost projection. The v1.14 P19 phase extends the + window to v1.11–v1.14. The project is reclassified as an **OSS reference implementation** (G-003), not a sponsored product. The grill's sponsor/ROI/budget/timeline axes apply diff --git a/README.md b/README.md index 84c82a9..8e77dfe 100644 --- a/README.md +++ b/README.md @@ -222,7 +222,7 @@ The workflow implements the same stages as `pipelines/contract.yml` (validate-contract → resolve-stack → security checks → infrastructure plan → policy checks → confidence → evidence event → apply). A consumer repo invokes the reusable workflow via a **versioned tag** (floating MAJOR + -MINOR, e.g. `acdl/.github/workflows/deploy.yml@v1.6`). The workflow checks +MINOR, e.g. `acdl/.github/workflows/deploy.yml@v1.13`). The workflow checks out the consumer repo, then checks out the ACDL platform repo into the runner workspace, and runs `scripts/run_platform.sh` against the consumer's contract — the consumer never clones the platform repo or invokes its diff --git a/docs/architecture.md b/docs/architecture.md index e56d63d..1d0e3d2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -230,7 +230,7 @@ change to the modules/stack/confidence/audit. - A MAJOR bump requires a new registry entry (immutable publication); the old entry enters a 12-month deprecation window. - The central deploy pipeline is referenced by a floating MAJOR + MINOR tag - (e.g. `@v1.6`); patch fixes flow within the tag, breaking changes land + (e.g. `@v1.13`); patch fixes flow within the tag, breaking changes land under the next MINOR tag. See [Versioning](pipeline/versioning) for the consumer-facing details. diff --git a/docs/consumer-guide.md b/docs/consumer-guide.md index 0110d14..33d15f2 100644 --- a/docs/consumer-guide.md +++ b/docs/consumer-guide.md @@ -19,7 +19,7 @@ definitions. ```mermaid flowchart LR - A["your repo
(app code + contracts + CI definitions)"] -->|uses: acdl/.github/workflows/deploy.yml@v1.9| B + A["your repo
(app code + contracts + CI definitions)"] -->|uses: acdl/.github/workflows/deploy.yml@v1.13| B B["platform runners
(modules + pipelines + adapters + schemas)"] -->|contract -> resolver -> stack -> adapter
-> security checks -> infrastructure plan -> policy checks
-> confidence -> apply -> evidence event| C C["your resources in AWS"] ``` @@ -27,7 +27,7 @@ flowchart LR ## Versioning the `uses:` reference The central deployment pipeline is **always versioned with floating MAJOR -and MINOR tags** (e.g. `acdl/pipelines/contract.yml@v1.9`). Version +and MINOR tags** (e.g. `acdl/pipelines/contract.yml@v1.13`). Version constraints cannot be expressed inside the contract, so the tag in `uses:` is the only immutability lever a consumer has. See [Versioning](pipeline/versioning) for the full rationale. @@ -47,7 +47,7 @@ platform-managed. See [Environments](environments/). environment is bound, your first pipeline run emits a friendly onboarding prompt. See [Environments](environments/). - **Authorization to reference the central pipeline.** Onboarding grants - your repo the right to `uses: acdl/.github/workflows/deploy.yml@v1.9`. + your repo the right to `uses: acdl/.github/workflows/deploy.yml@v1.13`. Contact the platform team if you have not been onboarded. ## Step 1 — Create a consumer repo @@ -94,7 +94,7 @@ ACDL deployment workflow with a **versioned tag** (floating MAJOR + MINOR): ```yaml jobs: deploy: - uses: acdl/.github/workflows/deploy.yml@v1.9 + uses: acdl/.github/workflows/deploy.yml@v1.13 with: contract: .acdl/contract.yml environment: dev @@ -140,7 +140,7 @@ name: microservice | Field | Type | Required | Description | |-------|------|----------|-------------| -| `uses` | string | yes | Reference to the central deployment pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/contract.yml@v1.9`). Bare or `@main` references are discouraged. See [Versioning](pipeline/versioning). | +| `uses` | string | yes | Reference to the central deployment pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/contract.yml@v1.13`). Bare or `@main` references are discouraged. See [Versioning](pipeline/versioning). | | `module` | string | yes | Module name from the registry — any primitive or module (e.g. `static-assets`, `microservice`, `s3`). See the [module catalog](modules/). | | `environment` | string | yes | The platform-managed environment to deploy to (e.g. `dev`). See [Environments](environments/). | | `inputs` | object | yes | Module-specific inputs (see the module's README). | @@ -177,14 +177,14 @@ on: branches: [main] jobs: deploy: - uses: acdl/.github/workflows/deploy.yml@v1.9 + uses: acdl/.github/workflows/deploy.yml@v1.13 with: contract: .acdl/contract.yml ``` That is the entire consumer-side workflow. When you push to `main`: -1. The platform runner resolves `uses: acdl/.github/workflows/deploy.yml@v1.9` +1. The platform runner resolves `uses: acdl/.github/workflows/deploy.yml@v1.13` to the reusable workflow **at the pinned tag**. 2. A **platform-provided runner** checks out **your** repo. 3. The runner checks out the **ACDL platform repo** into the workspace — @@ -326,8 +326,8 @@ per-module extension points. Common examples: | Contract schema | `schemas/contract.schema.json` | JSON Schema for consumer contracts. | | Stack schema | `schemas/stack.schema.json` | JSON Schema for the resolved stack instance. | | Module catalog | [modules/](modules/) | All primitives and modules. | -| Sample contract | `contracts/static-assets.yaml` | The reference example contract (uses `@v1.9`). | -| Sample contract | `contracts/microservice.yaml` | The microservice example contract (uses `@v1.9`). | +| Sample contract | `contracts/static-assets.yaml` | The reference example contract (uses `@v1.13`). | +| Sample contract | `contracts/microservice.yaml` | The microservice example contract (uses `@v1.13`). | | Module examples | `modules//examples/` | Validated per-module example contracts (`simple.yaml` + `complex.yaml`). | | Contract resolver | `core/contract_resolver.py` | Resolves contracts to stack instances. | | Angine adapter | `adapters/terraform/adapter.py` | Compiles stack instances to infrastructure. | @@ -353,7 +353,7 @@ destruction: use `mode: decommission` with the `changeRequestId` input: ```yaml - uses: acdl/.github/workflows/deploy.yml@v1.8 + uses: acdl/.github/workflows/deploy.yml@v1.13 with: contract: .acdl/contract.yml mode: decommission @@ -421,7 +421,7 @@ name: static-assets ``` **Shape 2 — single contract + `environment` workflow input:** the -reusable deploy workflow (`acdl/.github/workflows/deploy.yml@v1.9`) +reusable deploy workflow (`acdl/.github/workflows/deploy.yml@v1.13`) declares an `environment` input. When non-empty, it overrides the contract's `environment` field at load time (before interpolation), so the same contract can be promoted by passing a different environment: @@ -436,7 +436,7 @@ on: workflow_dispatch: required: true jobs: deploy-qa: - uses: acdl/.github/workflows/deploy.yml@v1.9 + uses: acdl/.github/workflows/deploy.yml@v1.13 with: environment: qa contract: .acdl/contract.yml diff --git a/docs/pipeline/index.md b/docs/pipeline/index.md index fecb96b..d5a738e 100644 --- a/docs/pipeline/index.md +++ b/docs/pipeline/index.md @@ -39,7 +39,7 @@ It is exposed to consumer repos as a **reusable workflow**: - `.github/workflows/deploy.yml` — GitHub Actions (production) A consumer repo invokes the reusable workflow via a **versioned tag** -(floating MAJOR + MINOR, e.g. `acdl/.github/workflows/deploy.yml@v1.6`). +(floating MAJOR + MINOR, e.g. `acdl/.github/workflows/deploy.yml@v1.13`). The workflow checks out the consumer repo, then checks out the ACDL platform repo into the runner workspace, and runs `scripts/run_platform.sh` against the consumer's contract. The consumer never clones the platform repo or diff --git a/docs/pipeline/versioning.md b/docs/pipeline/versioning.md index 185ab89..ac354e8 100644 --- a/docs/pipeline/versioning.md +++ b/docs/pipeline/versioning.md @@ -26,7 +26,7 @@ tag** in a consumer's CI workflow definition: ```yaml jobs: deploy: - uses: acdl/.github/workflows/deploy.yml@v1.6 + uses: acdl/.github/workflows/deploy.yml@v1.13 with: contract: .acdl/contract.yml ```