acdl/.ciagent/ROADMAP.md

ACDL — Roadmap

Overview

• v1.0 (demo): complete — tag v1.1.0, 2026-07-21. All 5 phases shipped + audited PASS.
• v1.1 (complete): architecture finalization + v1 spike. 5 phases (06–10). Tag v1.2.0, 2026-07-21. All 5 phases shipped + verified; review READY TO SHIP (0 P0); audit CLEAN. Gitea release id 202.
• v1.2 (complete): platform hardening + first real consumer deployment. 6 phases (11–16). Tag v1.3.0, 2026-07-21. All 6 phases shipped + verified; review READY TO SHIP (1 P0 operator action, 1 P1 deferred); audit CLEAN.
• v1.3 (complete): module documentation + thin-composition removal. The L2 composition layer is removed; module READMEs are built out. Tag v1.3.2.
• v1.4 (complete): central pipeline contract + shell reproducibility + output streaming. A declarative pipeline contract (schemas/pipeline.schema.json + pipelines/ci.yaml) binds the Gitea and GitHub workflows to a single source of truth. scripts/run_ci.sh mirrors the CI pipeline locally. scripts/run_platform.sh streams terraform/checkov output by default.
• v1.5 (complete, tag v1.5.0): consumer happy path + zero-trust docs + reusable deploy workflow. README rewritten so the consumer model is unambiguous (consumer owns only contract + app code; the rest is the platform source). Platform-flow + consumer-guide diagrams converted to mermaid. Legacy surface + implementation nomenclature removed from docs. Credentials section rewritten for zero-trust OIDC + ABAC (with a static-key override + daily rotation). A generic docs/CONSUMER_GUIDE.md (all L2 modules, versioned uses:, consumer-scoped prereqs, run-time platform fetch) replaces the module-specific guide. A byte-identical reusable deploy.yml workflow (Gitea + GitHub) implements pipelines/deploy.yaml and is invoked by consumer repos via a versioned tag.
• v1.6 (complete, tag v1.6.0): consumer-facing docs restructure + terminology normalization + environments concept. docs/ becomes a Jekyll-style GitHub Pages site. acdl_platform/ is renamed to core/. L2 → "modules", L1 → "primitives", "composition" → "pattern" in prose. README restructured: Features + Roadmap (no internal status), repository roles restated (consumer = app code + contracts + CI definitions), mermaid fixed (visible text, security-checks + infrastructure-apply stages, no tool names), credentials section minus go-gitea/waivers. Platform-managed environments concept + a minimal onboarding scaffold. .ciagent/ + .gitea/ references removed from all consumer-facing docs.
• v1.0 demo URL: https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html

---

v1.0 (Prior — the demo, complete)

Five-phase breakdown that took ACDL from empty repo to a reproducible 4-act executive demo. Milestone v1.0-initial covered the full demo build. Each phase produced a runnable increment and ended with a phase-completion commit

• tag. All phases complete; demo archived to demo/ in v1.1 Phase 06.

Phases

Phase 01 — repo-scaffolding

• Description: Create the three repos under continuous-intelligence (acdl-contracts, acdl-evidence; acdl already exists), seed directory layouts, configure Pages on acdl-evidence, add environment protection for qa and prod on acdl-contracts.
• Status: complete (v1.0.1)
• Depends on: —
• Requirements: REQ-01, REQ-09, REQ-10
• Success Criteria:
  • acdl-contracts and acdl-evidence exist and are pushable.
  • acdl-evidence Pages returns 200 with placeholder index.html.
  • qa and prod environments exist on acdl-contracts.

Phase 02 — l1-modules

• Description: Create all 8 L1 module folders under acdl/modules/l1/, each with manifest.yaml (declared inputs) and mock_apply.sh (uniform echo + 1s sleep + exit 0).
• Status: complete (v1.0.2)
• Depends on: [1]
• Requirements: REQ-02, REQ-03
• Success Criteria:
  • All 8 L1s present; mock_apply.sh runs and exits 0 for each.
  • manifest.yaml validates against the L1 schema.

Phase 03 — l2-modules-and-core-scripts

• Description: Create the 4 L2 compositions under acdl/modules/l2/ referencing L1s, plus the 5 core scripts in acdl/scripts/ (mock_executor.sh, policy_checker.py, confidence_signal.py, evidence_writer.py, l3b_agent_stub.py).
• Status: complete (v1.0.3)
• Depends on: [2]
• Requirements: REQ-04, REQ-05, REQ-06, REQ-07
• Success Criteria:
  • mock_executor.sh applies each L1 in an L2 and writes state.json.
  • policy_checker.py fails on public-ingress: true with POLICY_VIOLATION:PUBLIC_INGRESS.
  • confidence_signal.py returns 0.90 (pass) / 0.40 (fail).
  • evidence_writer.py appends an event with a valid hash chain.
  • l3b_agent_stub.py maps the Act 3 example issue to l2-commodity-price-feed.

Phase 04 — pipeline-and-approval-gates

• Description: Build the reusable pipeline workflow in acdl/.gitea/workflows/ (Dev → QA → Prod → Finalize) plus the issue-triggered L3B workflow in acdl-contracts/.gitea/workflows/. Wire environment protection for QA and Prod.
• Status: complete (v1.0.4)
• Depends on: [3]
• Requirements: REQ-08, REQ-09, REQ-10, REQ-12
• Success Criteria:
  • Pushing a valid contract.yaml runs Dev automatically and pauses at QA.
  • Approving QA moves to Prod; approving Prod finalizes.
  • Opening an Issue with the Act 3 text generates a contract.yaml commit and triggers the pipeline.

Phase 05 — evidence-ui-and-demo-dry-run

• Description: Build index.html (vanilla JS, fetches audit.json, renders timeline) and run all four acts end-to-end as a dry run.
• Status: complete (v1.0.5)
• Depends on: [4]
• Requirements: REQ-11, REQ-13, REQ-14, REQ-15
• Success Criteria:
  • Pages timeline renders events from audit.json.
  • Act 2: valid contract passes through all gates; timeline shows the full flow.
  • Act 3: Issue text produces the expected l2-commodity-price-feed contract and triggers the pipeline.
  • Act 4: malicious public-ingress: true contract halts in Dev with confidence < 0.50 and a visible rejection reason on the timeline.

---

v1.1 (Complete — architecture finalization + v1 spike, 2026-07-21, tag v1.2.0)

Five-phase breakdown to finalize the architecture to v1.0 and prove the locked commitments with one end-to-end implementation spike. Milestone v1.1-spike covered the real platform's first materialization. Ship tag at milestone COMPLETE: v1.2.0 (feature milestone, next minor per ship.md). Status: COMPLETE — all 5 phases shipped (v1.1.1..v1.1.5) + verified; review READY TO SHIP (0 P0); audit CLEAN; Gitea release id 202. D-034 closed (root key deactivated by user).

Phase 06 — archive-demo-and-reorient

• Description: Move the v1.0 demo (modules/, scripts/, evidence-ui/, contracts/, demo .gitea/workflows/) to demo/. Establish the new repo layout (platform/, schemas/, adapters/, terraform/, modules-ir/). Rewrite README to reflect the real platform. Verify the demo still runs from demo/ (regression check).
• Status: complete (v1.1.1)
• Depends on: —
• Requirements: (no new REQ; repo hygiene)
• Success Criteria:
  • demo/ contains the full v1.0 demo; demo/scripts/run_demo.sh --no-upload still exits 0.
  • New top-level dirs exist and are empty-but-scaffolded: platform/, schemas/, adapters/, terraform/, modules-ir/.
  • README reflects the real platform (vision + architecture links, new layout).

Phase 07 — architecture-v1-finalization

• Description: Resolve the 11 open decisions in docs/architecture.md §13 (already recorded in PROJECT.md). Author the locked schemas + designs: schemas/ir.schema.json (REQ-17), schemas/policy_check_result.schema.json (REQ-18), schemas/contract.schema.json (REQ-22), platform/confidence_signal.py spec (REQ-19), platform/audit_ledger_design.md (REQ-20), platform/hitl_matrix_design.md (REQ-21). Mark architecture v1.0.
• Status: complete (v1.1.2)
• Depends on: [06]
• Requirements: REQ-16, REQ-17, REQ-18, REQ-19, REQ-20, REQ-21, REQ-22
• Success Criteria:
  • All 11 open decisions resolved and recorded in PROJECT.md.
  • All 6 schema/design files exist and validate (ajv / python -m jsonschema).
  • docs/architecture.md status note updated to v1.0 (or a docs/architecture-v1.0.md snapshot).

Phase 08 — aws-oidc-bootstrap

• Description: Re-scoped per RESEARCH TARGET 1 + D-039. Gitea Actions does not support id-token: write (conf 0.95), so real OIDC is deferred to v1.2. This phase instead: uses the temporary long-lived key (waiver D-034) once to create an S3 state bucket, a DynamoDB lock/outbox table, and an IAM user with a minimal scoped policy (S3 + DynamoDB + plan-only); stores the key as a Gitea Actions secret; implements scripts/rotate_spike_key.sh to rotate the key after each spike run. Real OIDC federation is tracked via go-gitea/gitea#36988 for v1.2.
• Status: complete (v1.1.3)
• Depends on: [07]
• Requirements: REQ-23 (re-interpreted: AWS auth bootstrap + state backend; OIDC deferred to v1.2 per D-039)
• Success Criteria:
  • S3 state bucket + DynamoDB lock/outbox table exist.
  • An IAM user with a minimal scoped policy exists; its access key is stored as a Gitea Actions secret.
  • scripts/rotate_spike_key.sh rotates the key (deactivates old, creates new, updates the secret) and is idempotent.
  • A workflow step authenticates to AWS with the rotated secret and runs aws sts get-caller-identity successfully.
  • D-034 is closed: the bootstrap long-lived key is rotated/deactivated (logged in PROJECT.md).

Phase 09 — v1-spike-ir-and-l1-and-adapter

• Description: Implement the Target Stack IR, one real L1 l1-s3 (IR-typed interface, registered), and the Terraform adapter that compiles the IR → Terraform variable/output + root module and emits a real terraform plan against AWS (via the rotated-key secret per D-039; OIDC is v1.2). State in S3 + DynamoDB.
• Status: complete (v1.1.4)
• Depends on: [08]
• Requirements: REQ-24, REQ-26
• Success Criteria:
  • schemas/ir.schema.json is satisfied by modules-ir/l1/l1-s3/ interface.
  • The Terraform adapter translates l1-s3 to a valid terraform plan (real AWS).
  • terraform validate + terraform plan succeed; no long-lived credential in the workflow.

Phase 10 — v1-spike-l2-and-contract-e2e

• Description: Implement l2-static-asset (thin-composition referencing l1-s3), the contract schema + contract→IR resolution, and one end-to-end contract submission (contracts/spike.yaml for l2-static-asset) flowing through schema validation → IR resolution → terraform plan → Checkov PolicyCheckResult → confidence signal → evidence event to the DynamoDB outbox. Verify the IR commitments hold (no polyglot mess).
• Status: complete (v1.1.5)
• Depends on: [09]
• Requirements: REQ-25, REQ-27, REQ-28
• Success Criteria:
  • l2-static-asset references l1-s3 only (depth 1).
  • One contract submission completes the full pipeline end-to-end.
  • scripts/verify_phase10.sh proves the adapter is the only substrate-specific code.
  • Evidence event is written to the DynamoDB outbox.

After Phase 10: COMPLETE gate — review → ship v1.2.0 → audit. DONE.

---

v1.2 (Complete — platform hardening + first real consumer deployment, 2026-07-21, tag v1.3.0)

Six-phase breakdown to harden the v1.1 spike, simplify the setup, update the docs, and prove the platform delivers real value by deploying a basic microservice to AWS ECS Fargate end-to-end. Ship tag at milestone COMPLETE: v1.3.0 (feature milestone, next minor per ship.md — v1.1 shipped v1.2.0). Phase patches v1.2.1..v1.2.6. Status: COMPLETE — all 6 phases shipped (v1.2.1..v1.2.6) + verified; review READY TO SHIP (1 P0 operator action, 1 P1 deferred to v1.3); audit CLEAN. The terraform apply is blocked by the live IAM policy (P0-IAM, operator action); the platform flow is verified end-to-end up to terraform plan (13 to add).

Phase 11 — v1.2-research-and-readme

• Description: Re-evaluate go-gitea/gitea#36988 (OIDC for Gitea Actions) — confirm still open (re-checked 2026-07-21: open, last updated 2026-05-27, not merged) and record the decision to extend D-039 as D-047. Audit the v1.1 spike for NFR gaps (least-privilege IAM, idempotency, error handling, rotation hygiene) and simplification opportunities (script consolidation, dead code, stale paths). Rewrite README.md to reflect v1.1 complete + the actual spike flow + how to run + the real repo layout + the v1.2 objective.
• Status: complete (v1.2.1)
• Depends on: —
• Requirements: REQ-29
• Success Criteria:
  • RESEARCH.md has a v1.2 addendum with the #36988 re-check + NFR audit + simplification findings.
  • README.md reflects v1.1 complete; documents the spike flow, scripts/run_platform.sh, the repo layout, and the v1.2 objective; no stale "v1.1 (active)" framing.
  • D-047 is recorded in PROJECT.md.

Phase 12 — nfr-harden-and-simplify

• Description: Apply Phase 11's findings. Tighten terraform/bootstrap/spike_runner_policy.json to least-privilege (add ECS + ECR + ELB + IAM plan-only permissions for v1.2; audit for wildcards). Make create_state_backend.py and create_iam_user.py idempotent. Consolidate run_spike_plan.sh + run_spike_e2e.sh into a single scripts/run_platform.sh with proper exit codes and error handling. Redact P1-1 (the two AWS access key IDs in .ciagent/VERIFY.md Phase 09 narrative). Fix any remaining stale platform/ paths in .ciagent/. The v1.1 spike still runs e2e after the refactor.
• Status: complete (v1.2.2)
• Depends on: [11]
• Requirements: REQ-30
• Success Criteria:
  • scripts/run_platform.sh runs the full v1.1 spike e2e and exits 0.
  • create_state_backend.py / create_iam_user.py re-runs are idempotent (no duplicate resources; exit 0).
  • spike_runner_policy.json passes a least-privilege audit (no * actions beyond documented exceptions).
  • .ciagent/VERIFY.md Phase 09 narrative has no live AWS access key IDs.
  • No stale platform/ paths remain in .ciagent/.

Phase 13 — l1-catalog-for-ecs

• Description: Author six IR-typed L1 modules for an ECS Fargate microservice: l1-vpc (VPC + subnets + route tables), l1-ecs-cluster (ECS Fargate cluster), l1-ecs-service (ECS service + task definition), l1-iam-role (task execution + task role), l1-alb (ALB + listener + target group), l1-ecr (ECR repository). Each has an interface.json valid against schemas/ir.schema.json. Register all six in modules-ir/registry.json. Expand the Terraform adapter TYPE_MAP to cover the new IR resource types. Each L1 produces a valid terraform plan fragment.
• Status: complete (v1.2.3)
• Depends on: [12]
• Requirements: REQ-31
• Success Criteria:
  • All six L1s exist under modules-ir/l1/ with interface.json valid against schemas/ir.schema.json.
  • modules-ir/registry.json lists all six.
  • The adapter TYPE_MAP covers all six IR resource types.
  • Each L1 produces a valid terraform plan fragment.

Phase 14 — l2-microservice-and-contract-schema

• Description: Author l2-microservice thin-composition under modules-ir/l2/l2-microservice/ referencing the six ECS L1s (depth ≤ 5). Extend schemas/contract.schema.json with microservice inputs (image: string, port: integer, env: map, healthcheck: object). Verify contract→IR resolution yields a complete target stack.
• Status: complete (v1.2.4)
• Depends on: [13]
• Requirements: REQ-32
• Success Criteria:
  • l2-microservice references the six ECS L1s only (depth ≤ 5).
  • schemas/contract.schema.json validates a contracts/microservice.yaml with the new inputs.
  • Contract→IR resolution yields a complete target stack (all six L1 instances + relationships).

Phase 15 — consumer-repo-and-terraform-apply

• Description: Create a new Gitea repo acdl-consumer-microservice under the continuous-intelligence org containing a basic HTTP microservice (tiny Python/Go server returning 200), a Dockerfile, an ECR push step, and a contracts/microservice.yaml submission for l2-microservice (dev environment). Lift the platform from plan to apply for the dev environment (autonomous per §10, confidence ≥ 0.50, no HITL). Submit the contract → pipeline → IR → plan → apply → a real ECS Fargate service running.
• Status: complete (v1.2.5, PARTIAL — terraform apply blocked by IAM P0)
• Depends on: [14]
• Requirements: REQ-33 (partial), REQ-34
• Success Criteria:
  • acdl-consumer-microservice repo exists under continuous-intelligence.
  • The microservice builds into a Docker image and is pushed to ECR.
  • terraform apply (dev) creates real AWS resources (VPC, ECS cluster, ECR repo, ALB, ECS service).
  • The apply result is captured in the evidence stream.

Phase 16 — v1.2-capstone-e2e

• Description: End-to-end verification: consumer commit to acdl-consumer-microservice triggers the pipeline → contract→IR resolution → terraform plan → terraform apply (dev) → a live ECS Fargate service serving HTTP 200 on its ALB → evidence event written to the DynamoDB outbox → the event renders on the acdl-evidence timeline. Verify the NFR improvements from Phase 12 hold, the setup is simpler (one scripts/run_platform.sh), and the README is accurate. scripts/verify_phase16.sh proves the full flow green.
• Status: complete (v1.2.6, capstone — terraform apply blocked by IAM P0, verified up to plan)
• Depends on: [15]
• Requirements: REQ-35 (partial — IAM-blocked)
• Success Criteria:
  • One consumer commit produces a live ECS service serving HTTP 200.
  • An evidence event for the apply is in the DynamoDB outbox and renders on the timeline.
  • scripts/verify_phase16.sh exits 0.
  • README accurately documents the v1.2 platform flow.

After Phase 16: COMPLETE gate — review → ship v1.3.0 → audit.

---

v1.3 (Complete — module documentation + thin-composition removal)

The v1.3 milestone starts with simplification: removing the unsatisfactory thin-composition layer and building out proper module documentation. The L2 composition mechanism will be redesigned in a later phase.

Phase 17 — remove-thin-composition-and-module-readmes

• Description: Remove the L2 thin-composition layer completely (composition.json files, contract_resolver.py, contract schema, sample contracts) and build out proper module READMEs. Create a README template for both L1 and L2 modules, rewrite all 7 L1 module READMEs in plain language (no jargon, with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning sections), write 2 L2 placeholder READMEs noting the composition is under redesign, create a catalog index, and patch run_platform.sh to load a pre-existing IR instance instead of resolving a contract. Prune L2 entries from the registry.
• Status: complete (v1.3.1)
• Depends on: —
• Requirements: REQ-36, REQ-37, REQ-38
• Success Criteria:
  • The thin-composition layer is fully removed (composition.json, contract_resolver.py, contract schema, contracts/).
  • run_platform.sh loads a pre-existing IR instance; the downstream adapter/checkov/confidence/outbox pipeline still works.
  • A README-TEMPLATE.md exists for both L1 and L2 modules.
  • Every L1 module has a README.md with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning.
  • Every L2 module has a placeholder README.md noting the composition is under redesign.
  • A modules-ir/README.md catalog index exists.

Phase 18 — testing-and-cicd-pipelines

• Description: Create a pytest test suite that reproduces the platform pipeline offline (adapter, confidence_signal, checkov_adapter, outbox_writer). Add an offline --check-only mode to run_platform.sh that runs the pipeline up to adapter emission without AWS/Checkov/outbox. Create identical CI/CD pipelines for both Gitea Actions (.gitea/workflows/ci.yml, dev environment) and GitHub Actions (.github/workflows/ci.yml, production) that run: lint, pytest, run_platform.sh --check-only. Add pyproject.toml + requirements-test.txt for dependency pinning.
• Status: complete (v1.3.2)
• Depends on: [17]
• Requirements: REQ-39, REQ-40, REQ-41, REQ-42
• Success Criteria:
  • pytest runs and passes offline (no AWS, no Checkov, no DynamoDB).
  • run_platform.sh --check-only runs offline and exits 0.
  • .gitea/workflows/ci.yml and .github/workflows/ci.yml exist with identical job stages (lint, test, check-only).
  • pyproject.toml + requirements-test.txt pin test dependencies.

After Phase 18: COMPLETE gate — review → ship v1.3.2 → audit.

---

v1.4 (Active — central pipeline contract + shell reproducibility + streaming)

The v1.4 milestone makes the CI/CD pipeline a declarative contract rather than duplicated workflow copies, enables full shell reproducibility of the CI pipeline, and streams terraform/checkov output so users can see what the platform is doing.

Phase 19 — central-pipeline-contract-and-shell-reproducibility

• Description: Create a central pipeline contract (schemas/pipeline.schema.json JSON Schema + pipelines/ci.yaml YAML instance) that both .gitea/workflows/ci.yml (Gitea Actions, dev) and .github/workflows/ci.yml (GitHub Actions, production) implement. Create scripts/run_ci.sh that mirrors the CI pipeline locally (lint → test → check-only). Update scripts/run_platform.sh to stream terraform init/validate/plan output, Checkov compliance results, and PolicyCheckResult records to stdout by default (with --quiet for log-only mode). Add tests/test_pipeline_contract.py validating the contract schema, workflow conformance, and run_ci.sh. Update both workflow YAMLs with contract reference headers (staying byte-identical).
• Status: complete (v1.4.1)
• Depends on: [18]
• Requirements: REQ-43, REQ-44, REQ-45
• Success Criteria:
  • pipelines/ci.yaml validates against schemas/pipeline.schema.json.
  • Both .gitea/workflows/ci.yml and .github/workflows/ci.yml are byte-identical.
  • A test parses both workflows and asserts their stages/commands match the contract.
  • scripts/run_ci.sh exits 0 and outputs "CI PIPELINE OK".
  • scripts/run_platform.sh --check-only streams the emitted Terraform to stdout.
  • scripts/run_platform.sh --check-only --quiet suppresses the Terraform stream.
  • pytest total count increases from 90 to 122 (32 new contract/streaming tests).

After Phase 19: COMPLETE gate — review → ship v1.4.1 → audit.

---

v1.5 (Complete — consumer happy path + zero-trust docs + reusable deploy workflow, tag v1.5.0)

The v1.5 milestone makes the consumer happy path self-evident, documents the zero-trust credential model, and provides a reusable deploy workflow so consumer repos never need to clone the platform repo or invoke its scripts locally.

Phase 20 — consumer-happy-path-and-reusable-deploy-workflow

• Description: Rewrite README.md so the consumer model is unambiguous (this repo is the platform source; a consumer owns only contract.yaml + app code). Convert the platform-flow diagram to a mermaid flowchart TD. Remove "L3A"/"L3B" + "spike" nomenclature from README prose. Rewrite the Credentials section for zero-trust OIDC + ABAC (with a static-key override + daily rotation; consumer rotates out of band when using .env.secrets locally). Replace docs/consumer-guide-static-asset.md with a generic docs/CONSUMER_GUIDE.md (all L2 modules, mermaid diagrams, versioned uses: floating MAJOR+MINOR, consumer-scoped prerequisites, run-time platform fetch via a reusable workflow). Create byte-identical .gitea/workflows/deploy.yml + .github/workflows/deploy.yml implementing pipelines/deploy.yaml — a reusable workflow invoked by consumer repos via uses: acdl/.gitea/workflows/deploy.yml@v1.4 that checks out the consumer repo + the ACDL platform repo and runs scripts/run_platform.sh. Update contracts/static-asset.yaml to uses: acdl/pipelines/deploy.yaml@v1.4. Extend tests/test_pipeline_contract.py to validate the new deploy workflows (byte-identical, schema-conformant).
• Status: complete (v1.5.0)
• Depends on: [19]
• Requirements: REQ-46, REQ-47, REQ-48, REQ-49, REQ-50, REQ-51
• Success Criteria:
  • README.md states the platform-source vs consumer-repo distinction up front; platform flow is a mermaid flowchart TD; grep L3B README.md returns 0 hits; grep -i spike README.md returns 0 prose hits (code paths in bash blocks allowed).
  • docs/CONSUMER_GUIDE.md exists; docs/consumer-guide-static-asset.md is deleted; grep -R consumer-guide-static-asset returns 0 dangling references; guide is generic (static-asset is the worked example, not the scope); diagrams are mermaid; uses: references use @v1.4.
  • README.md Credentials section describes OIDC + ABAC zero-trust as the default and the static-key override + daily rotation + consumer out-of-band rotation duty for local .env.secrets.
  • .gitea/workflows/deploy.yml and .github/workflows/deploy.yml exist, are byte-identical, conform to schemas/deploy-pipeline.schema.json, and are reusable (on: workflow_call with a contract input).
  • contracts/static-asset.yaml uses uses: acdl/pipelines/deploy.yaml@v1.4.
  • tests/test_pipeline_contract.py validates the deploy workflows (exist, byte-identical, schema-conformant); the extended test suite passes; bash scripts/run_ci.sh exits 0.

After Phase 20: COMPLETE gate — review → ship v1.5.0 → audit.

---

v1.6 (Active — consumer-facing docs restructure + terminology normalization + environments concept)

The v1.6 milestone restructures the consumer-facing documentation into a real GitHub Pages site, normalizes the terminology (L2 → "modules", L1 → "primitives", "composition" → "pattern", "forge" → "platform runners"), renames acdl_platform/ to platform/, rewrites the README (Features + Roadmap, restated repository roles, fixed mermaid, cleaned credentials section), removes all .ciagent/ + .gitea/ references from consumer surfaces, and introduces the concept of platform-managed environments with a minimal first-run onboarding scaffold.

Phase 21 — docs-restructure-and-terminology-normalization

• Description: Rename acdl_platform/ → platform/ (directory + all code/test/script/pipeline/workflow references; tests green). Restructure docs/ into a Jekyll-style GitHub Pages site (_config.yml, index.md, modules/, contracts/, pipeline/, environments/, consumer-guide.md, consolidated architecture.md, vision.md). Rewrite README.md: remove .ciagent/ + .gitea/workflows/ rows; restate consumer repo model (app code + 1+ contracts + CI definitions uses:-ing the central workflow); replace Status with Features + Roadmap (planned only); fix the mermaid (visible text, add security-checks stage before policy, no tool names, add infrastructure-apply stage); remove the environments table; clean the credentials section (no go-gitea/waivers, keep daily/out-of-band rotation); forge → platform runners/platform-managed. Update docs/consumer-guide.md: drop L2 (→ modules), composition → pattern (prose), remove .gitea/ (GitHub only), forge → platform runners, mermaid updated. Update modules/ READMEs: L1 → primitives, L2 → modules, composition → pattern (prose only, files kept); bump stale @v1 → @v1.4. Consolidate docs/architecture.md + docs/architecture-v1.0.md into a single current-architecture docs/architecture.md. Add docs/environments/index.md (platform-managed AWS account/network/state/runner; consumer provides none). Add a minimal onboarding scaffold: platform/environments/ dir + sample dev.json + README, platform/environment_check.py, wire-in at the top of scripts/run_platform.sh, friendly onboarding message when no environment is defined, tests/test_environment_check.py. Add a roadmap entry: "composition" will later describe the thin orchestration where consumers dynamically create a module directly from the contract file (future implementation, not this phase).
• Status: complete (v1.6.0)
• Depends on: [20]
• Requirements: REQ-52, REQ-53, REQ-54, REQ-55, REQ-56, REQ-57, REQ-58, REQ-59, REQ-60, REQ-61
• Success Criteria:
  • grep -R "\.ciagent" docs/ README.md returns 0 hits; grep -R "\.gitea" docs/ README.md modules/ contracts/ returns 0 hits.
  • grep -R "acdl_platform" . (excluding .ciagent/, demo/, .git/) returns 0 hits; the test suite passes after the rename.
  • docs/ has the Jekyll structure (_config.yml, index.md, modules/, contracts/, pipeline/, environments/); no .ciagent/ links in docs/.
  • Consumer-facing docs have no "L2"/"L1" labels (modules/primitives) and no "forge" term; "composition" → "pattern" in prose.
  • README.md has Features + Roadmap (no version changelog); repository roles restated; mermaid visible + security-checks + infrastructure-apply stages + no tool names; no environments table; credentials section has no go-gitea/waivers.
  • docs/environments/index.md exists; platform/environments/ + dev.json + environment_check.py + run_platform.sh wire-in + tests/test_environment_check.py exist and pass.
  • bash scripts/run_ci.sh exits 0; python3 -m pytest tests/ -v passes (154 + new environment-check tests).

After Phase 21: COMPLETE gate — review → ship v1.6.0 → audit. DONE.