acdl/.ciagent/PROJECT.md

# ACDL — Agentic Cloud Delivery Platform

## Vision / Core Value

A 30-minute executive demo proving that infrastructure can be delivered **automatically, safely, and with a complete audit trail** — without the usual weeks of manual tickets, reviews, and copy-pasted configuration. Because the demo runs entirely on **local stubs** (no AWS/GCP/Azure, no external LLM APIs), it shows intent and safety behavior rather than provisioning real cloud resources.

## Objective

Build a runnable demo (Linux + GitHub/Gitea Actions) that walks executives through four acts:

1. **Act 1 — The Friction:** the old manual 2-week deployment process.
2. **Act 2 — Developer Self-Service:** commit a valid `contract.yaml` for `l2-commodity-price-feed`, watch Dev auto-run, QA + Prod approval gates, then the evidence timeline.
3. **Act 3 — Citizen Developer:** open a GitHub Issue with natural-language intent; the Python keyword parser generates the same `contract.yaml` and triggers the identical pipeline.
4. **Act 4 — The Safety Net:** commit a malicious `contract.yaml` (`public-ingress: true`) for `l2-regulatory-reporting`; the pipeline halts in Dev because the confidence signal drops below 0.50, and the rejection is visible on the evidence stream.

## Requirements

### Validated
- Three repos under the `continuous-intelligence` Gitea org: `acdl` (platform + stubs + reusable workflows), `acdl-contracts` (developer surface), `acdl-evidence` (GitHub Pages audit timeline).
- L1 modules (single-purpose, substrate-agnostic, max-depth-1 primitives) as folders with `manifest.yaml` + `mock_apply.sh`.
- L2 modules (composed stacks, max-depth-5) grouping L1s into deployable service shapes.
- L3A developer surface: commit `contract.yaml` to `acdl-contracts`.
- L3B agentic surface: Python keyword parser turning an Issue body into `contract.yaml`.
- Confidence signal: base 0.90, drops to 0.40 on policy violation; gate threshold ≥ 0.50.
- Evidence stream: hash-chained `audit.json` published via Pages + vanilla-JS `index.html` timeline.
- Reusable CI workflow: Dev (autonomous) → QA (manual approval) → Prod (manual approval) → finalize.

### Active
- 8 L1 modules (serverless/container focus): `l1-eks-fargate`, `l1-iam-role`, `l1-lambda`, `l1-api-gateway`, `l1-eventbridge`, `l1-sqs`, `l1-s3`, `l1-cloudwatch`.
- 4 L2 modules mirroring S&P Global Energy / Platts use cases: `l2-invoice-service`, `l2-commodity-price-feed`, `l2-energy-analytics-api`, `l2-regulatory-reporting`.
- 5 core scripts: `mock_executor.sh`, `policy_checker.py`, `confidence_signal.py`, `evidence_writer.py`, `l3b_agent_stub.py`.
- Issue-triggered workflow in `acdl-contracts` that runs the L3B parser, commits a new branch, closes the issue, and triggers the main pipeline.
- Evidence stream UI (`index.html`) fetching `audit.json` and rendering events as a timeline.

### Out of Scope
- Real cloud provisioning (AWS/GCP/Azure).
- Real LLM inference / external AI APIs.
- Production-grade infrastructure or multi-tenant isolation.
- Real cryptographic tamper-proofing (the hash chain is demonstrative, not adversarially secure).

## Constraints

- Environment: local Linux OS.
- CI/CD: GitHub/Gitea Actions + Environments (QA, Prod approval gates).
- **No cloud** — absolutely no AWS, GCP, or Azure resources.
- **No AI** — no OpenAI or external LLM APIs; the "Agentic" part is a keyword parser.
- All state in flat JSON files or CI artifacts.
- Compute strategy: EKS Fargate + serverless primitives (no VPC module).
- L1 modules are single-purpose, substrate-agnostic, do not compose with other L1s.
- L2 modules combine L1 primitives into deployable shapes, max depth 5.

## Context

- Forge: Gitea at `https://git.cloudinit.dev`, org `continuous-intelligence`.
- The `acdl` repo already exists (empty) at org root and serves as the platform/meta repo.
- `acdl-contracts` and `acdl-evidence` will be created as additional repos in the same org.
- act_runner / Gitea Actions is the CI runtime; "GitHub Actions" workflow YAML is reused as-is.

## Key Decisions

| ID | Decision | Rationale | Outcome |
|----|----------|-----------|---------|
| D-001 | Use Gitea org `continuous-intelligence` for all repos | User-specified target org; already exists | Single source of truth for the demo |
| D-002 | Map "GitHub Actions" to Gitea Actions (act_runner) | Environment is Gitea; same workflow YAML syntax | Demo runs on the actual forge |
| D-003 | Collapse `acdl-platform` into the existing `acdl` repo | `acdl` already exists empty at org root | 3 repos total: `acdl`, `acdl-contracts`, `acdl-evidence` |
| D-004 | Use Gitea `environment` blocks + required reviewers for QA/Prod; fallback to manual `workflow_dispatch` with approval input | Approval gates required by spec; forge supports environment protection | Frictionless approval gates |
| D-005 | Hash-chained ledger (`prev_hash` + own `hash`) for evidence; declared demonstrative | Spec asks for simple JSON; chain gives visible tamper-evidence | Visible audit timeline without overengineering |
| D-006 | Confidence gate threshold = 0.50 exactly | Explicit in spec | Acts 2/4 behave as scripted |
| D-007 | Each `mock_apply.sh` echoes `[L1: <name>] applying...` + `OK`, sleeps 1s, exits 0 | Spec literal; uniformity aids timeline parsing | Predictable evidence events |
| D-008 | Keyword→stack mapping for L3B: gas/price/ingest/data-lake → commodity-price-feed; invoice/billing → invoice-service; analytics/historical/query → energy-analytics-api; regulatory/compliance/reporting/trading → regulatory-reporting; fallback → invoice-service | Mirrors the 4 L2 modules + Act 3 example issue | Act 3 reproduces deterministic behavior |
| D-009 | Init milestone = `v1.0`, branch `milestone/v1.0-initial` | init.md Step 5 mandate | Branching strategy follows convention |
| D-010 | Single-project mode for the `acdl` checkout | User chose standalone single-project | `---ci---` blocks omit `project:` field |