docs(init): initialize Agentic Cloud Delivery Platform (5 phases)

---ci---
phase: 0
milestone: v1.0
status: specify
decisions:
  - id: D-001
    decision: Use Gitea org continuous-intelligence for all ACDL repos
    rationale: User-specified target org; already exists at git.cloudinit.dev
    confidence: 0.95
    alternatives: [new dedicated demo org]
  - id: D-002
    decision: Map "GitHub Actions" to Gitea Actions (act_runner) using same workflow YAML
    rationale: Environment is Gitea; syntax-compatible with act_runner
    confidence: 0.85
    alternatives: [migrate to GitHub.com, raw shell scripts]
  - id: D-003
    decision: Collapse acdl-platform into the existing empty acdl repo
    rationale: acdl already exists at org root; avoids a 4th repo
    confidence: 0.90
    alternatives: [create separate acdl-platform repo]
  - id: D-004
    decision: Use Gitea environment blocks + required reviewers for QA/Prod; fallback to manual workflow_dispatch with approval input
    rationale: Spec mandates approval gates; forge supports environment protection
    confidence: 0.80
    alternatives: [external approval bot, no approval gates]
  - id: D-005
    decision: Hash-chained ledger (prev_hash + own hash via SHA-256 of canonical JSON) for evidence; declared demonstrative not adversarially secure
    rationale: Spec asks for simple JSON; chain gives visible tamper-evidence
    confidence: 0.85
    alternatives: [signed commits only, full Merkle tree]
  - id: D-006
    decision: Confidence gate threshold = 0.50 exactly (base 0.90, fail drops to 0.40)
    rationale: Explicit in spec
    confidence: 0.99
    alternatives: []
  - id: D-007
    decision: Each mock_apply.sh echoes "[L1: <name>] applying..." + "OK", sleeps 1s, exits 0
    rationale: Spec literal; uniformity aids timeline parsing
    confidence: 0.95
    alternatives: [randomized sleep durations]
  - id: D-008
    decision: L3B keyword->stack mapping: 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
    rationale: Mirrors the 4 L2 modules + Act 3 example issue text
    confidence: 0.85
    alternatives: [single default stack, ML classifier (forbidden by no-AI constraint)]
  - id: D-009
    decision: Init milestone = v1.0, branch milestone/v1.0-initial
    rationale: init.md Step 5 mandates milestone/v1.0-initial
    confidence: 0.99
    alternatives: []
  - id: D-010
    decision: Single-project mode for the acdl checkout; ---ci--- blocks omit project field
    rationale: User chose standalone single-project; no other projects in this checkout
    confidence: 0.90
    alternatives: [register acdl in /root multi-project config]
---/ci---

Specification: 30-minute executive demo of the Agentic Cloud Delivery Platform proving automatic, safe, audited infra delivery via local stubs on Gitea Actions (no cloud, no AI APIs).
Requirements: [3 repos under continuous-intelligence org, 8 L1 stub modules, 4 L2 composed modules mirroring S&P Global Energy use cases, 5 core scripts (mock_executor.sh, policy_checker.py, confidence_signal.py, evidence_writer.py, l3b_agent_stub.py), reusable Dev->QA->Prod pipeline with approval gates, issue-triggered L3B agent, Pages evidence timeline UI, 4 scripted demo acts]
Constraints: [local Linux OS, Gitea Actions + Environments, no AWS/GCP/Azure, no external LLM APIs, state in flat JSON/artifacts, EKS Fargate + serverless primitives (no VPC module), L1 single-purpose substrate-agnostic max-depth-1, L2 max-depth-5]
Out of scope: [real cloud provisioning, real LLM inference, production-grade infrastructure, adversarial tamper-proofing of evidence]
This commit is contained in:
Jon Chery
2026-07-21 12:46:33 +00:00
commit e3416f8e77
5 changed files with 321 additions and 0 deletions
+70
View File
@@ -0,0 +1,70 @@
# ACDL — Architecture (initial)
> Initial architecture for the ACDL demo. May be incomplete; refined at phase boundaries.
## Overview
The demo is a three-repo, stub-driven system that simulates an autonomous cloud delivery platform. No real cloud or AI is used; every "infrastructure" action is a bash/Python stub that emits structured evidence. The platform is driven by either a developer-supplied `contract.yaml` (L3A) or a natural-language GitHub Issue parsed by a keyword script (L3B), then flows through an autonomous Dev stage, manual QA and Prod approval gates, and finally publishes a hash-chained audit trail to a Pages site.
```
┌──────────────── acdl-contracts ─────────────────┐
Developer ───▶ │ commit contract.yaml Issue (NL intent) │
└────────────┬───────────────────┬────────────────┘
│ (push) │ (issue opened)
▼ ▼
┌─────────────────┐ ┌──────────────────────┐
│ reusable │ │ issue workflow → │
│ pipeline │ │ l3b_agent_stub.py → │
│ (acdl repo) │ │ contract.yaml → push │
└────────┬────────┘ └──────────────────────┘
┌────────────────────┼────────────────────┐
▼ ▼ ▼
Dev (autonomous) QA (approval) Prod (approval)
mock_executor.sh environment gate environment gate
policy_checker.py
confidence_signal.py
evidence_writer.py ──▶ audit.json (hash-chained) ──▶ acdl-evidence
index.html (Pages)
timeline UI
```
## Components
| Name | Description | Boundaries | Depends On |
|------|-------------|-----------|------------|
| `acdl` repo | Platform meta repo: reusable workflows, L1/L2 stub modules, core scripts | Owns workflows + stubs; does not hold contracts or evidence | — |
| L1 modules | Single-purpose infra primitives (EKS Fargate, IAM, Lambda, API Gateway, EventBridge, SQS, S3, CloudWatch) | One folder per L1; `manifest.yaml` + `mock_apply.sh`; do not compose with other L1s | `acdl` repo |
| L2 modules | Composed stacks (invoice, commodity-price-feed, energy-analytics-api, regulatory-reporting) | Reference L1s by name; max depth 5; expressed as a composition manifest | L1 modules |
| `mock_executor.sh` | Reads an L2 composition, invokes each L1 `mock_apply.sh`, writes `state.json` | Bash; reads L2 manifest + L1 manifests | L1/L2 modules |
| `policy_checker.py` | Reads `contract.yaml`; fails on forbidden keys (e.g. `public-ingress: true`) | Python; emits `POLICY_VIOLATION:<REASON>` or pass | contract.yaml |
| `confidence_signal.py` | Base 0.90; on policy failure drops to 0.40 and echoes reason | Python; calls policy_checker | policy_checker.py |
| `evidence_writer.py` | Appends an event to `audit.json`, links to previous event via SHA-256 chain | Python; canonical-JSON hashing | audit.json |
| `l3b_agent_stub.py` | Parses Issue text by keywords, emits `contract.yaml` | Python keyword map; no external APIs | contract.yaml schema |
| `acdl-contracts` repo | Developer + agentic entry surface; holds contracts + issue workflow | Triggers main pipeline on push | `acdl` reusable workflow |
| `acdl-evidence` repo | Pages host for `audit.json` + `index.html` timeline | Read-only for the pipeline; written at finalize stage | evidence_writer.py output |
| Reusable pipeline workflow | Dev → QA → Prod → Finalize stages with environment gates | Gitea Actions; calls core scripts | All core scripts |
## Data Flow
1. A `contract.yaml` arrives either by direct push (L3A) or by the issue workflow running `l3b_agent_stub.py` (L3B).
2. Push to `acdl-contracts` triggers the reusable pipeline in the `acdl` repo.
3. **Dev stage:** `policy_checker.py` validates the contract; `mock_executor.sh` applies the L2 composition's L1s; `confidence_signal.py` computes the score; `evidence_writer.py` records each step. If score < 0.50, the stage fails and evidence records the rejection.
4. **QA stage:** the workflow pauses on the `qa` environment; a human approves.
5. **Prod stage:** same gate on the `prod` environment.
6. **Finalize:** the workflow commits the updated `audit.json` to `acdl-evidence`; Pages republishes `index.html`, which fetches and renders the timeline.
## Build Order
1. Repo scaffolding: create `acdl-contracts` and `acdl-evidence` in the org; seed `acdl` directory layout.
2. L1 modules (8 stubs).
3. L2 modules (4 compositions).
4. Core scripts (`mock_executor.sh`, `policy_checker.py`, `confidence_signal.py`, `evidence_writer.py`, `l3b_agent_stub.py`).
5. Reusable pipeline workflow (Dev → QA → Prod → Finalize) + environment gates.
6. Issue-triggered L3B workflow in `acdl-contracts`.
7. Evidence UI (`index.html` + Pages config).
8. Demo dry-run + the four scripted acts.
+72
View File
@@ -0,0 +1,72 @@
# 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 |
+66
View File
@@ -0,0 +1,66 @@
# ACDL — Requirements
## v1
### Category: Repos & Org
- **REQ-01:** All demo code lives under the `continuous-intelligence` Gitea org at `https://git.cloudinit.dev`.
- **REQ-09:** Three repos exist: `acdl` (platform + stubs + reusable workflows), `acdl-contracts` (developer surface), `acdl-evidence` (Pages audit timeline).
### Category: L1 Modules
- **REQ-02:** 8 L1 module folders exist under `acdl/modules/l1/`: `l1-eks-fargate`, `l1-iam-role`, `l1-lambda`, `l1-api-gateway`, `l1-eventbridge`, `l1-sqs`, `l1-s3`, `l1-cloudwatch`.
- **REQ-03:** Each L1 module has a `manifest.yaml` (declaring inputs) and a `mock_apply.sh` that echoes success, sleeps 1s, and exits 0.
### Category: L2 Modules
- **REQ-04:** 4 L2 modules exist under `acdl/modules/l2/`: `l2-invoice-service`, `l2-commodity-price-feed`, `l2-energy-analytics-api`, `l2-regulatory-reporting`, each composing the specified L1s.
- **REQ-05:** L2 modules compose L1 primitives into deployable shapes with a maximum depth of 5.
### Category: Core Scripts
- **REQ-06:** `mock_executor.sh` reads an L2 composition, invokes each L1 `mock_apply.sh`, and writes `state.json`.
- **REQ-07:** `policy_checker.py` reads `contract.yaml` and fails with `POLICY_VIOLATION:PUBLIC_INGRESS` on `public-ingress: true`; otherwise passes.
- **REQ-08:** `confidence_signal.py` returns a base score of 0.90 and drops to 0.40 (with reason code) when policy fails; gate threshold is ≥ 0.50.
### Category: Evidence Stream
- **REQ-11:** `evidence_writer.py` appends events to `audit.json` and links each event to the previous via a SHA-256 hash chain (`prev_hash` + own `hash`).
- **REQ-13:** `acdl-evidence` is Pages-enabled and serves `audit.json` plus `index.html`.
### Category: Pipeline
- **REQ-10:** The reusable pipeline runs Dev (autonomous), pauses at QA (manual approval), pauses at Prod (manual approval), then finalizes by committing `audit.json` to `acdl-evidence`.
- **REQ-12:** Opening an Issue in `acdl-contracts` runs `l3b_agent_stub.py`, commits a generated `contract.yaml` to a new branch, closes the Issue, and triggers the main pipeline.
### Category: Demo Acts
- **REQ-14:** `index.html` uses vanilla JS to fetch `audit.json` from the Pages URL and render events as a timeline.
- **REQ-15:** All four demo acts (Friction, Developer Self-Service, Citizen Developer, Safety Net) reproduce deterministically in a dry run.
## v2
(None — v1 covers the complete demo.)
## Out of Scope
| Feature | Reason |
|---------|--------|
| Real cloud provisioning (AWS/GCP/Azure) | Demo explicitly stubs all infrastructure; no cloud access available. |
| Real LLM inference / external AI APIs | Spec forbids external AI; L3B is a keyword parser. |
| Production-grade infrastructure | Demo target is a 30-minute executive show, not a production system. |
| Adversarial tamper-proofing of evidence | Hash chain is demonstrative; not cryptographically secure against a determined attacker. |
| Multi-tenant isolation | Out of demo scope. |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| REQ-01 | 1 | pending |
| REQ-02 | 2 | pending |
| REQ-03 | 2 | pending |
| REQ-04 | 3 | pending |
| REQ-05 | 3 | pending |
| REQ-06 | 3 | pending |
| REQ-07 | 3 | pending |
| REQ-08 | 3 | pending |
| REQ-09 | 1 | pending |
| REQ-10 | 4 | pending |
| REQ-11 | 3 | pending |
| REQ-12 | 4 | pending |
| REQ-13 | 5 | pending |
| REQ-14 | 5 | pending |
| REQ-15 | 5 | pending |
+59
View File
@@ -0,0 +1,59 @@
# ACDL — Roadmap
## Overview
Five-phase breakdown to take ACDL from empty repo to a reproducible 4-act executive demo. Milestone `v1.0-initial` covers the full demo build. Each phase produces a runnable increment and ends with a phase-completion commit + tag.
## 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:** not_started
- **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:** not_started
- **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:** not_started
- **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:** not_started
- **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:** not_started
- **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.
+54
View File
@@ -0,0 +1,54 @@
{
"projects": [
{
"slug": "acdl",
"name": "Agentic Cloud Delivery Platform",
"milestone": "v1.0",
"status": "specify"
}
],
"active_project": "acdl",
"autonomy": {
"level": "full",
"escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
"clarify_budget": 10,
"decision_confidence_threshold": 0.6,
"max_revision_iterations": 3,
"max_verification_retries": 2,
"escalation_timeout_ms": 300000
},
"model_profile": "quality",
"parallelization": {
"enabled": true,
"max_concurrent_agents": 5,
"min_plans_for_parallel": 2,
"max_concurrent_projects": 3
},
"verification": {
"automated_only": true,
"escalate_visual": true,
"escalate_external_integration": true,
"test_first": false
},
"security": {
"auto_accept_low_severity": true,
"auto_mitigate_medium_severity": true,
"escalate_high_severity": true
},
"git": {
"branching_strategy": "phase",
"auto_commit": true,
"auto_push": true
},
"sessions": {
"max_concurrent_sessions": 3,
"session_timeout_ms": 3600000,
"session_isolation": "branch"
},
"gitea": {
"base_url": "https://git.cloudinit.dev",
"api_token_env": "b8fa72220e350314704a8a28a0e570b418bb4655",
"owner": "continuous-intelligence",
"repo": "acdl"
}
}