Compare commits
14 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jon Chery
|
ecb2c78d11 | ||
|
Jon Chery
|
4ab15cb7a5 | ||
|
Jon Chery
|
e044a2de0d | ||
|
Jon Chery
|
b927f9026a | ||
|
Jon Chery
|
930c24be6d | ||
|
Jon Chery
|
087c89edbf | ||
|
Jon Chery
|
288607b3fa | ||
|
Jon Chery
|
30e63d6cb5 | ||
 grimacing
|
b84a8a2241 | ||
|
grimacing
|
7614c41530 | ||
|
grimacing
|
52665b8f0c | ||
|
Jon Chery
|
d700148063 | ||
|
Jon Chery
|
80ac975e61 | ||
|
Jon Chery
|
58adf9e231 |
+248
-270
@@ -1,323 +1,301 @@
|
||||
# ACDL — Architecture (initial)
|
||||
# ACDL — Architecture (v1.1 target)
|
||||
|
||||
> Initial architecture for the ACDL demo. May be incomplete; refined at phase boundaries.
|
||||
> Target architecture for the real Agentic Cloud Delivery Platform.
|
||||
> Source of truth for **how**: `docs/architecture.md` (v0.2) is the upstream
|
||||
> draft; this file is the ACDL-repo operating copy, refined at phase
|
||||
> boundaries. Where this file and `docs/vision.md` conflict, the vision wins.
|
||||
|
||||
## Status
|
||||
|
||||
Architecture is at **v0.2** upstream (`docs/architecture.md`). Milestone v1.1
|
||||
**finalizes it to v1.0** in Phase 07 by resolving the 11 open decisions
|
||||
(see `PROJECT.md` open-decision resolutions table). This file records the
|
||||
locked commitments and the v1.1 spike scope.
|
||||
|
||||
## 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.
|
||||
The platform is **four layers + six cross-cutting concerns**. The sixth
|
||||
concern — the substrate abstraction (§12) — is first-class, not an
|
||||
implementation detail. The vision's "Two Consumer Surfaces, One Platform"
|
||||
tenet binds everything: L3A and L3B converge on the same contract schema,
|
||||
the same policy envelope, and the same evidence stream.
|
||||
|
||||
```
|
||||
┌──────────────── 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
|
||||
┌──────────── acdl-contracts ────────────┐
|
||||
Developer ───▶ │ commit contract.yaml │ (L3A)
|
||||
Citizen dev ──▶ │ Issue → agent → contract.yaml │ (L3B)
|
||||
└────────────────┬───────────────────────┘
|
||||
│ (push)
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ central pipeline │
|
||||
│ (acdl repo, Gitea │
|
||||
│ Actions / act_runner) │
|
||||
└────────┬─────────────┘
|
||||
│
|
||||
┌─────────────────────────┼─────────────────────────┐
|
||||
▼ ▼ ▼
|
||||
contract→IR resolution policy (Checkov/Kyverno) confidence signal
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
Terraform adapter ──▶ terraform plan ──▶ PolicyCheckResult ──▶ {score,band}
|
||||
│ │
|
||||
▼ ▼
|
||||
dev (autonomous, ≥0.50) qa (HITL, ≥0.75) prod (HITL, ≥0.90) dr (HITL, ≥0.95)
|
||||
│
|
||||
▼
|
||||
evidence_writer.py ──▶ audit.json (hash-chained) ──▶ acdl-evidence
|
||||
│
|
||||
▼
|
||||
index.html (Pages)
|
||||
timeline UI
|
||||
DynamoDB outbox ──▶ S3 Object Lock (7-yr, source of truth) ──▶ GitHub audit repo (hot index)
|
||||
│
|
||||
▼
|
||||
acdl-evidence (timeline UI)
|
||||
```
|
||||
|
||||
## Components
|
||||
## Layers
|
||||
|
||||
| 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 |
|
||||
| `evidence-ui/index.html` | Vanilla-JS timeline UI (Phase 05); fetches `./audit.json` and renders events | Single HTML file with inline CSS+JS; no frameworks (REQ-14) | `audit.json` on `acdl-evidence` main |
|
||||
| `scripts/run_demo.sh` | Phase 05 dry-run simulation of the 4 demo acts; calls core scripts + writes evidence + uploads `audit.json` + `index.html` to `acdl-evidence` | Bash; uses `evidence_writer.py` + `finalize_evidence.py` + the file-contents API | All Phase 03/04 artifacts |
|
||||
### Layer 1 — Foundational Primitives
|
||||
Single-purpose, **substrate-agnostic** primitive modules. L1 modules do
|
||||
not compose with other L1s; L1 takes its environment as input. The L1
|
||||
interface is defined against the **Target Stack IR**, not against Terraform
|
||||
directly (the IR is shaped to round-trip to Terraform in v1, per §12.1).
|
||||
|
||||
## Phase 04 pipeline topology (research)
|
||||
- No inter-L1 references. L1 may call Terraform data sources.
|
||||
- Semver: interface → MAJOR, behavior → MINOR, lifecycle → PATCH (W3.D).
|
||||
- Immutability on publication. 12-month deprecation window.
|
||||
- AI refinement is a flag; the trigger is the W1.A joint condition.
|
||||
|
||||
Gitea Actions limitations (confirmed via research, supersedes any
|
||||
GitHub-Actions assumptions):
|
||||
### Layer 2 — Composed Stacks
|
||||
Combine L1 primitives into deployable shapes. Each codebase maps to one
|
||||
canonical L2 stack (`multiStack: true` only per W1.B). Shape X
|
||||
(parameterized module) or Shape Y (thin-composition layer). Hierarchical
|
||||
composition, max depth 5, only registered L1s. The thin-composition tree's
|
||||
`wires` field is defined against the IR's relationship type, not a Terraform
|
||||
module block.
|
||||
|
||||
- `actions/upload-artifact@v3` / `download-artifact@v3` work; v4 is NOT supported by act_runner.
|
||||
- Artifacts are scoped to a single workflow run; **re-dispatch starts a new run, so artifacts do NOT survive between dispatches**.
|
||||
- `workflow_dispatch` API: `POST /api/v1/repos/{owner}/{repo}/actions/workflows/{filename}.yml/dispatches` with body `{ "ref": "<branch>", "inputs": {...} }`.
|
||||
- `on: workflow_call` + `uses: <owner>/<repo>/.gitea/workflows/<file>@<ref>` works; pin to `@milestone/v1.0-initial`.
|
||||
- `actions/checkout@v4` supports cross-repo (pass `repository:` + `ref:` + `token: ${{ secrets.GITEA_TOKEN }}` for private repos).
|
||||
- File-contents API: POST to create (201), PUT to update (must include current `sha`, obtained via GET).
|
||||
- `${{ secrets.GITEA_TOKEN }}` is a manually-created PAT secret on the `acdl` + `acdl-contracts` repos; the auto-injected token is current-repo only and cannot cross-repo.
|
||||
- No native approval-gate UI; gates are `workflow_dispatch` inputs (`approve_qa`, `approve_prod`).
|
||||
Pipeline quality checks: secrets-in-plaintext, public ingress, IAM
|
||||
wildcard, KMS key reference, tag compliance, naming convention. Restricted
|
||||
from thin-composition: IAM principal creation, network boundary creation,
|
||||
key/secret creation, external data transfer. Auto-promote after 3 observed
|
||||
usages.
|
||||
|
||||
### Approval-gate + state-persistence approach (D-027, D-028 refined)
|
||||
### Layer 3A — Developer Consumer Surface
|
||||
Tag-based reference to the central pipeline template. Developer-owned
|
||||
workflow file, no platform auto-sync. L3A and L3B are parallel paths, not a
|
||||
progression. **W2.A (Path B):** tag for dev/qa, SHA for prod; platform CLI
|
||||
resolves tag→SHA for prod-bound workflows.
|
||||
|
||||
Because re-dispatch starts a new run and artifacts do not survive:
|
||||
### Layer 3B — Agentic Consumer Surface
|
||||
Hybrid runtime, skill as markdown, agent as executor. Trust model: trust
|
||||
and always verify on the platform side. Skill envelope (4 dimensions).
|
||||
Stateless agents, all state in the platform. `profile: agentic` marker
|
||||
unlocks `naturalLanguageIntent`, `confidenceAtSubmission`, `agentTrace`.
|
||||
Initial skill catalog (BA.A): web API, worker, scheduled job, static asset,
|
||||
basic observability bootstrap.
|
||||
|
||||
1. The pipeline workflow has `workflow_dispatch` inputs:
|
||||
- `contract-ref` (string; default `main`) — the ref on `acdl-contracts` carrying the contract.
|
||||
- `approve_qa` (boolean; default `false`) — the human sets this to `true` to advance past QA.
|
||||
- `approve_prod` (boolean; default `false`) — the human sets this to `true` to advance past Prod.
|
||||
Environment progression:
|
||||
|
||||
2. Each stage job (`dev`, `qa-gate`, `prod-gate`, `finalize`) writes its evidence to `acdl-evidence` via the file-contents API (PUT `audit.json` with the new event appended). This is the persistent state across re-dispatches.
|
||||
| Environment | Autonomy | Attester | Gate |
|
||||
|---|---|---|---|
|
||||
| dev | Full autonomy (no HITL) | — | Confidence ≥ 0.50, all six inputs present |
|
||||
| qa | Held for attestation | QA | GitHub Deployment approval + full QA matrix (§10) |
|
||||
| prod | Held for attestation | SRE | GitHub Deployment approval + full SRE matrix (§10) |
|
||||
| dr | Held for attestation | SRE | GitHub Deployment approval + dr-drill evidence |
|
||||
|
||||
3. **Dev stage** (always runs on dispatch): check out `acdl` + `acdl-contracts@<contract-ref>`, run `policy_checker.py` + `confidence_signal.py`; if `score < 0.50`, write a `dev_rejected` evidence event and exit 1 (Act 4). Otherwise run `mock_executor.sh`, write a `dev_applied` evidence event, and exit 0. The run ends here.
|
||||
**Staging is removed.** Dev is the only autonomous environment.
|
||||
|
||||
4. **QA gate** (next dispatch with `approve_qa=true`): check out, run `evidence_writer.py --stage qa --event "qa approved"`, commit updated `audit.json` to `acdl-evidence`. Exit 0. The run ends.
|
||||
## Cross-cutting concerns
|
||||
|
||||
5. **Prod gate** (next dispatch with `approve_prod=true`): same as QA but `--stage prod`.
|
||||
### Central pipeline template (§6)
|
||||
JSON Schema (draft 2020-12) with a thin domain wrapper. Central repo +
|
||||
generated client libraries. Multi-stage validation: schema → policy → NFR →
|
||||
confidence. Distributed enrichment. GitOps reconciler (K8s API; cdlc-gitops
|
||||
state → CRDs) + Terraform execution layer (§12.5). The pipeline emits one
|
||||
`PolicyCheckResult` per policy rule; the confidence signal consumes them as
|
||||
one normalized input.
|
||||
|
||||
6. **Finalize** (same dispatch as Prod, chained via `needs: prod-gate`): write the `finalize` evidence event, commit final `audit.json` to `acdl-evidence`. The raw URL now serves the updated timeline.
|
||||
### Contract schema (§7)
|
||||
Central repo + generated client libraries. Strict fail-fast at schema
|
||||
stage, multi-stage validation with reason codes from a published
|
||||
vocabulary. **W3.E:** per-env mandatory inputs —
|
||||
- dev: `stack`, `environment`
|
||||
- qa adds: `validation.e2eSuite`, `validation.loadTest`
|
||||
- prod adds: `runbook`, `dashboard`, `oncall`
|
||||
- dr adds: `drDrillRef`
|
||||
- `inputs` always optional; `profile: agentic` fields optional everywhere.
|
||||
|
||||
Because each stage is a separate dispatch, the workflow file uses `if:` conditions on each job:
|
||||
- `dev` runs when `inputs.approve_qa != true && inputs.approve_prod != true` (the initial dispatch).
|
||||
- `qa-gate` runs when `inputs.approve_qa == true && inputs.approve_prod != true`.
|
||||
- `prod-gate` runs when `inputs.approve_prod == true`.
|
||||
- `finalize` runs after `prod-gate` (`needs: prod-gate`).
|
||||
### Confidence signal (§8)
|
||||
Six canonical inputs, weighted sum with per-input breakdown. Per-env
|
||||
thresholds: dev ≥ 0.50, qa ≥ 0.75, prod ≥ 0.90, dr ≥ 0.95. Structured output
|
||||
`{ score, band, perInput, reasonCodes }`. 1-year storage, no retraining in
|
||||
v1. Halt with explicit reason on missing input.
|
||||
|
||||
This means a full pipeline = 3 dispatches (initial, qa-approve, prod-approve). The human drives each via the Gitea UI or the dispatch API.
|
||||
Policy input = list of `PolicyCheckResult` records (engine-agnostic).
|
||||
Severity → penalty: critical → hard override to mandatory block; high →
|
||||
-0.2; medium → -0.05; low → -0.01; info → 0.0. One critical finding
|
||||
hard-overrides the score regardless of all other inputs.
|
||||
|
||||
## Phase 05 dry-run + UI (research)
|
||||
**BA.B:** thresholds frozen for v1; tuning begins v1.2 (quarterly FP/FN
|
||||
tracking; override = Infra & Ops + SRE joint sign-off, itself a
|
||||
confidence-event).
|
||||
|
||||
Phase 05 has no act_runner available in this environment, so the "dry run"
|
||||
is a local bash simulation (`scripts/run_demo.sh`) that produces the same
|
||||
`audit.json` shape a real pipeline run would, then uploads it (plus the
|
||||
UI) to `acdl-evidence` via the file-contents API. The simulation covers:
|
||||
### Audit and evidence stream (§9)
|
||||
Tiered ledger: **S3 with Object Lock in compliance mode** (cold, source of
|
||||
truth, 7-year retention) + **GitHub audit repo** (`acdl-evidence`, hot
|
||||
query index, not part of the chain). Daily checkpoints. Event schema: JWS
|
||||
detached signature, `prev_event_hash` chain, controlled-vocabulary
|
||||
`event_type`. Outbox pattern: local durable outbox + async worker.
|
||||
|
||||
- **Act 1 — Friction:** a single evidence event "manual 2-week deployment (legacy process)" at `stage: dev` with a red-colored timeline marker.
|
||||
- **Act 2 — Developer Self-Service:** `l2-commodity-price-feed` contract, full pipeline (dev → qa → prod → finalize), 4 evidence events.
|
||||
- **Act 3 — Citizen Developer:** Issue body fed to `l3b_agent_stub.py`, generates the same `l2-commodity-price-feed` contract, identical pipeline, 4 evidence events.
|
||||
- **Act 4 — Safety Net:** `l2-regulatory-reporting` contract with `public-ingress: true`, dev rejects (confidence 0.40 < 0.50), 1 evidence event "dev rejected: POLICY_VIOLATION:PUBLIC_INGRESS".
|
||||
Outbox database = **DynamoDB**. RPO = 0 (synchronous write to local outbox
|
||||
before contract submission ack); RTO = async worker's dead-letter recovery.
|
||||
Single-region in v1. The outbox also stores per-contract QA and prod
|
||||
approver identities (the only durable record outside GitHub's audit log).
|
||||
|
||||
The `audit.json` after `run_demo.sh` contains the genesis + all act
|
||||
events (typically ~14 events). The UI fetches `./audit.json` and renders
|
||||
a vertical timeline with stage-colored markers and a per-event hash
|
||||
preview.
|
||||
### Human-in-the-Loop mechanics (§10)
|
||||
Pre-execution gates. qa, prod, dr are PR-based attestation gates backed by
|
||||
GitHub Environments with required reviewers. No partial deployment to roll
|
||||
back on rejection (qa, prod); dr is a separate GitHub Deployment against a
|
||||
separate cluster/region.
|
||||
|
||||
### UI rendering contract (D-032, D-033)
|
||||
Reviewer routing: GitHub CODEOWNERS + Environment required reviewers
|
||||
(qa → QA; prod → SRE; dr → SRE). CODEOWNERS routes, does not enforce
|
||||
identity distinctness.
|
||||
|
||||
`evidence-ui/index.html`:
|
||||
- Single file, inline CSS + JS, no external resources.
|
||||
- Fetches `./audit.json` (relative URL; works against any raw-URL origin).
|
||||
- Renders events as a vertical timeline; each event card shows `seq`, `ts`, `stage` (color-coded: `dev` blue, `qa` yellow, `prod` orange, `finalize` green, `genesis` gray, rejected events red), `event` text, and a 12-char hash preview (`hash.slice(0, 12)…`).
|
||||
- Handles fetch failure with a "No audit data yet" message.
|
||||
- Refresh button to re-fetch.
|
||||
**Separation of duties** (platform-internal, not GitHub-native, not Kyverno
|
||||
in v1): on dev→qa promotion the platform writes the QA approver's GitHub
|
||||
identity to the DynamoDB outbox keyed by `contractId`; on qa→prod it reads
|
||||
the stored QA approver and the new SRE approver; if equal, it blocks, emits
|
||||
`SEPARATION_OF_DUTIES_VIOLATION`, and routes a halt artifact to SRE on-call.
|
||||
|
||||
## Data Flow
|
||||
Full 8-concern attestation matrix (functional, performance, security
|
||||
posture, contract NFRs, operational readiness, incident response,
|
||||
capacity/cost, resilience) — see `docs/architecture.md` §10.4.
|
||||
|
||||
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.
|
||||
Timeout: 1 business day = warn + escalate; 2 business days = auto-freeze +
|
||||
re-submit (linked via `supersedes`). Rejection returns the contract to HELD;
|
||||
the audit chain is extended, not torn up.
|
||||
|
||||
## Build Order
|
||||
### Agentic stack (§11)
|
||||
Hybrid runtime: platform-managed control plane + consumer-owned agent.
|
||||
Versioned, signed skill catalog over MCP. Skill envelope enforced on
|
||||
invocation and result submission. Consumer-owned skill execution; the
|
||||
platform does not run the skill. Stateless agents, all state in the
|
||||
platform. Skills are reviewed for sensitive data before release (Infra &
|
||||
Ops owns the review; it is the mandatory release gate).
|
||||
|
||||
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.
|
||||
### Substrate execution (§12) — the binding constraint
|
||||
**Target Stack IR** (locked): a substrate-neutral description of resources
|
||||
(typed inputs/outputs/NFRs), relationships (single parent per child),
|
||||
composition (tree, max depth 5), and policy hooks. The L1 registry, L2
|
||||
thin-composition tree, contract YML, and PolicyCheckResult schema are all
|
||||
defined against the IR — none against any specific substrate.
|
||||
|
||||
## Gitea API Surface (Phase 01 research)
|
||||
**Substrate adapters** are the only substrate-specific code. An adapter
|
||||
compiles the IR into a substrate execution plan. **v1 ships exactly one
|
||||
adapter: the Terraform adapter.** v2+ may add OpenTofu, Pulumi, K8s CRDs
|
||||
without architectural change.
|
||||
|
||||
Authoritative findings from the Gitea docs (added in RESEARCH; supersedes any
|
||||
GitHub-Pages / GitHub-Environments assumptions carried over from the spec):
|
||||
v1 reality: the IR is shaped to round-trip cleanly to Terraform (nearly
|
||||
isomorphic). As more adapters appear, the IR gets more expressive and the
|
||||
adapters gain translation logic; the L1 content, the YML standard, and the
|
||||
thin-composition tree do not change.
|
||||
|
||||
| Capability | Gitea support | ACDL approach |
|
||||
|------------|---------------|---------------|
|
||||
| Org-scoped repo create | `POST /api/v1/orgs/{org}/repos` (`CreateRepoOption`) | Used to create `acdl-contracts` + `acdl-evidence` |
|
||||
| Native Pages | **None** (no `[pages]` config section) | Serve `acdl-evidence` via raw file URLs: `https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html`; `index.html` fetches `audit.json` from the same raw path. Requires `[cors] ENABLED=true` on the server if the UI is loaded cross-origin. |
|
||||
| Environments API | **None**; `jobs.<id>.environment` is ignored by act_runner | Model QA/Prod gates as `workflow_dispatch` approval inputs (D-004 / D-013); optionally create `qa` and `prod` branches as a visible stand-in |
|
||||
| `repository_dispatch` trigger | **Not supported** | Cross-repo trigger via `workflow_dispatch` API: `POST /api/v1/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches` called from a step using `$GITEA_TOKEN` |
|
||||
| Reusable workflows (`workflow_call`) | Supported | `acdl/.gitea/workflows/pipeline.yml` called via `uses: continuous-intelligence/acdl/.gitea/workflows/pipeline.yml@milestone/v1.0-initial` |
|
||||
| `workflow_dispatch` | Supported (trigger + API) | Used for the manual-approval fallback and the issue workflow's cross-repo trigger |
|
||||
| `issues.opened` trigger | Supported | Drives the L3B issue-trigger workflow in `acdl-contracts` |
|
||||
| `act_runner` labels | Single label only (`runs-on: ubuntu-latest`) | All workflows use `runs-on: ubuntu-latest` |
|
||||
| Context | `${{ gitea.* }}` and `${{ github.* }}` both work | Workflows use `gitea.*` for clarity |
|
||||
**Terraform adapter (v1):** translates IR-typed L1 interface → Terraform
|
||||
`variable`/`output` blocks; IR-typed L2 thin-composition tree → Terraform
|
||||
root module; IR-typed relationships → module references; emits a
|
||||
`terraform plan` from the IR. The adapter is a thin layer; it does not own
|
||||
L1/L2 content.
|
||||
|
||||
### Branch pinning rule
|
||||
State storage: S3 (state) + DynamoDB (locking), cloud-managed,
|
||||
single-region in v1.
|
||||
|
||||
The reusable workflow in the `acdl` repo lives on `milestone/v1.0-initial`
|
||||
(that is the repo's default branch). `uses:` references from `acdl-contracts`
|
||||
must pin to `@milestone/v1.0-initial`, not `@main` (the `acdl` repo has no
|
||||
`main` branch). The new repos `acdl-contracts` and `acdl-evidence` use
|
||||
`default_branch: "main"` (D-015) so their default branch exists immediately
|
||||
for pushes.
|
||||
Policy toolchain: **Checkov** for Terraform plan policy (the L2 checks +
|
||||
tag/naming); **Kyverno** for K8s-native/platform-internal policy; **OPA**
|
||||
reserved for cross-resource cases, explicitly last resort.
|
||||
|
||||
### Default verification toolchain
|
||||
|
||||
There is no `package.json`; ACDL is bash + python stubs. The verification gate
|
||||
substitutes `bash -n` and `python -m py_compile` for `npm run typecheck`, and
|
||||
per-phase `scripts/verify_phaseNN.sh` for `npm test`. `npm run build` is a
|
||||
no-op (no build step). See PERSONAS.md / VERIFICATION note.
|
||||
|
||||
## L1 module schema (Phase 02 research)
|
||||
|
||||
Each L1 module lives at `modules/l1/<name>/` with exactly two files:
|
||||
|
||||
- `manifest.yaml` — declares the L1's identity + a flat `inputs:` map.
|
||||
Schema (D-017):
|
||||
```yaml
|
||||
name: l1-eks-fargate # matches the folder name
|
||||
kind: l1 # literal "l1"; substrate-agnostic
|
||||
description: <one-line>
|
||||
inputs:
|
||||
<key>:
|
||||
description: <one-line>
|
||||
type: string # only "string" allowed (flat, max-depth-1)
|
||||
```
|
||||
- `mock_apply.sh` — uniform stub per D-007 + D-018:
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: <name>] applying..."
|
||||
sleep 1
|
||||
echo "[L1: <name>] OK"
|
||||
exit 0
|
||||
```
|
||||
`mock_apply.sh` does NOT read input values; the manifest is for traceability
|
||||
and for Phase 03's `mock_executor.sh` to enumerate the L1s in an L2.
|
||||
|
||||
### L1 list (fixed per REQ-02 / D-019)
|
||||
|
||||
| Folder | Description |
|
||||
|--------|-------------|
|
||||
| `l1-eks-fargate` | Serverless container compute substrate |
|
||||
| `l1-iam-role` | Identity and access role primitive |
|
||||
| `l1-lambda` | Event-driven function primitive |
|
||||
| `l1-api-gateway` | HTTP routing primitive |
|
||||
| `l1-eventbridge` | Event bus primitive |
|
||||
| `l1-sqs` | Queue primitive |
|
||||
| `l1-s3` | Object store primitive |
|
||||
| `l1-cloudwatch` | Observability primitive |
|
||||
|
||||
L1 modules are single-purpose, substrate-agnostic, max-depth-1 (per
|
||||
PROJECT.md Constraints). They do not compose with other L1s.
|
||||
|
||||
## L2 module schema + core scripts (Phase 03 research)
|
||||
|
||||
### L2 manifest.yaml schema (D-020)
|
||||
|
||||
```yaml
|
||||
name: l2-commodity-price-feed # matches the folder name
|
||||
kind: l2 # literal "l2"
|
||||
description: <one-line>
|
||||
l1s: # ordered list of L1 references
|
||||
- name: l1-eks-fargate # MUST match an existing L1 folder name
|
||||
inputs:
|
||||
cluster_name: price-feed-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: price-ingest
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
# ... up to 5 L1 references per L2 (max-depth-5 per REQ-05; L2->L1 is depth 1)
|
||||
```
|
||||
|
||||
L2s reference L1s **by name only** (no path); `mock_executor.sh` resolves
|
||||
the name to `modules/l1/<name>/`.
|
||||
|
||||
### L2 list (fixed per REQ-04)
|
||||
|
||||
| Folder | Description | L1s (per S&P Global Energy / Platts use cases) |
|
||||
|--------|-------------|------------------------------------------------|
|
||||
| `l2-invoice-service` | Billing + invoicing microservice | `l1-eks-fargate`, `l1-iam-role`, `l1-lambda`, `l1-sqs`, `l1-s3` |
|
||||
| `l2-commodity-price-feed` | Real-time price ingestion | `l1-eks-fargate`, `l1-lambda`, `l1-api-gateway`, `l1-eventbridge`, `l1-s3` |
|
||||
| `l2-energy-analytics-api` | Historical query API | `l1-eks-fargate`, `l1-api-gateway`, `l1-lambda`, `l1-s3`, `l1-cloudwatch` |
|
||||
| `l2-regulatory-reporting` | Compliance + reporting | `l1-eks-fargate`, `l1-iam-role`, `l1-lambda`, `l1-sqs`, `l1-s3` |
|
||||
|
||||
Each L2 references exactly 5 L1s (within the max-depth-5 constraint; L2→L1
|
||||
is depth 1, so depth-5 is generous but the spec caps composition depth at
|
||||
5 — the count is 5 to demonstrate a realistic composed stack).
|
||||
|
||||
### contract.yaml schema (D-021)
|
||||
|
||||
```yaml
|
||||
stack: l2-commodity-price-feed # MUST match an existing L2 folder name
|
||||
inputs: # top-level params for the L2 (optional)
|
||||
environment: dev
|
||||
owner: platform-team
|
||||
public-ingress: false # bool; true triggers POLICY_VIOLATION:PUBLIC_INGRESS
|
||||
```
|
||||
|
||||
The `public-ingress` key is the only policy-enforced field in Phase 03.
|
||||
Phase 04's pipeline reads `contract.yaml`, runs `policy_checker.py`, then
|
||||
`mock_executor.sh` to apply the L2.
|
||||
|
||||
### state.json shape (D-022)
|
||||
|
||||
`mock_executor.sh` writes `state.json` to its working directory:
|
||||
**Policy result normalization (§12.6):** the confidence signal consumes a
|
||||
normalized `PolicyCheckResult` schema, not raw engine output.
|
||||
|
||||
```json
|
||||
{
|
||||
"l2": "l2-commodity-price-feed",
|
||||
"l1s": [
|
||||
{"name": "l1-eks-fargate", "applied": true, "exit_code": 0},
|
||||
{"name": "l1-lambda", "applied": true, "exit_code": 0},
|
||||
...
|
||||
],
|
||||
"contract": {
|
||||
"stack": "l2-commodity-price-feed",
|
||||
"inputs": {...},
|
||||
"public-ingress": false
|
||||
}
|
||||
"contractId": "uuid",
|
||||
"evaluatedAt": "ISO-8601",
|
||||
"engine": "checkov | kyverno | opa",
|
||||
"ruleId": "CKV_AWS_24 | KYVERNO_NO_PRIVILEGED | ...",
|
||||
"severity": "critical | high | medium | low | info",
|
||||
"result": "pass | fail | skipped | error",
|
||||
"message": "human-readable",
|
||||
"evidence": { "...engine-specific, opaque to the signal..." },
|
||||
"resourceRef": "IR-typed resource identifier"
|
||||
}
|
||||
```
|
||||
|
||||
### audit.json event + hash chain (D-023)
|
||||
Execution layer: GitHub/Gitea Actions in the central pipeline repo. State
|
||||
locking via DynamoDB. **AWS credentials via OIDC federation — long-lived
|
||||
credentials are forbidden** (§12.5). The platform does not run
|
||||
`terraform apply` against a developer's workstation; all execution is in
|
||||
the central pipeline.
|
||||
|
||||
`audit.json` is a JSON array of event objects. `evidence_writer.py`
|
||||
appends one event per call. Hash chain:
|
||||
Registry maintenance: L1 publication updates the L1 registry in the same
|
||||
PR. The registry is the IR-typed contract, not a Terraform-specific
|
||||
variable schema.
|
||||
|
||||
1. Construct the event dict with `hash` set to empty string.
|
||||
2. Serialize via `json.dumps(event, sort_keys=True, separators=(",", ":"))` — canonical JSON (deterministic key order, no whitespace).
|
||||
3. Compute `hash = sha256(canonical_json.encode("utf-8")).hexdigest()`.
|
||||
4. Set `event["hash"] = hash`.
|
||||
5. Append to `audit.json`.
|
||||
Contract→IR resolution: the contract declares intent in IR-typed terms;
|
||||
the pipeline resolves it to a target stack (list of L1 instances + inputs +
|
||||
relationships); the Terraform adapter compiles the target stack to a plan.
|
||||
|
||||
Genesis event (when `audit.json` is empty or missing):
|
||||
## v1.1 spike scope
|
||||
|
||||
```json
|
||||
{
|
||||
"seq": 0,
|
||||
"ts": "2026-07-21T13:00:00Z",
|
||||
"stage": "genesis",
|
||||
"event": "audit log initialized",
|
||||
"prev_hash": "GENESIS",
|
||||
"hash": "<sha256 of the canonical json of this event with hash empty>"
|
||||
}
|
||||
```
|
||||
The spike (Phases 08–10) materializes the **minimum** that proves the IR
|
||||
commitments hold (no polyglot mess):
|
||||
|
||||
Subsequent events: `seq = prev.seq + 1`, `prev_hash = prev.hash`.
|
||||
- One L1: `l1-s3` (IR-typed interface; the only AWS resource in the spike).
|
||||
- One L2 thin-composition: `l2-static-asset` (references `l1-s3` only).
|
||||
- Terraform adapter: IR → `terraform plan` against AWS via OIDC.
|
||||
- One contract submission → contract→IR → `terraform plan` → Checkov
|
||||
`PolicyCheckResult` → confidence signal → evidence event to the DynamoDB
|
||||
outbox.
|
||||
- State: S3 + DynamoDB (real AWS, single-region).
|
||||
|
||||
### Core script I/O contracts
|
||||
Out of spike scope: full HITL matrix wiring, Kyverno, OPA, MCP skill
|
||||
catalog, GitOps reconciler, multi-region, prod/dr environments, the 5-skill
|
||||
L3B catalog. Those are post-spike (v1.2+) platform build-out.
|
||||
|
||||
| Script | Input | Output | Exit |
|
||||
|--------|-------|--------|------|
|
||||
| `mock_executor.sh` | `<contract.yaml path>` (argv[1]); reads L2 manifest from `modules/l2/<contract.stack>/manifest.yaml` | writes `state.json` to cwd; prints per-L1 progress | 0 on all-L1s-pass; non-zero on any L1 failure |
|
||||
| `policy_checker.py` | `<contract.yaml path>` (argv[1]) | stdout: `POLICY_PASS` or `POLICY_VIOLATION:PUBLIC_INGRESS` | 0 on pass; 1 on violation |
|
||||
| `confidence_signal.py` | `<contract.yaml path>` (argv[1]); calls policy_checker | stdout: `{"score": 0.90|0.40, "reason": "..."}` | 0 always (per D-024; pipeline decides gate) |
|
||||
| `evidence_writer.py` | argv: `--stage <dev|qa|prod|finalize|genesis>` `--event "<text>"` `--audit <path to audit.json>` (default `./audit.json`) | appends event to audit.json; prints the new event's hash + seq | 0 on success; 1 on I/O error |
|
||||
| `l3b_agent_stub.py` | argv[1] = issue body text (or stdin if no argv); optional `-o <path>` (default stdout) | writes a `contract.yaml` (D-021 schema) with `stack` set by the D-008 keyword map | 0 on success; 1 on empty input |
|
||||
## Gitea API surface (carried from v1.0, refined)
|
||||
|
||||
| Capability | Gitea support | ACDL approach (v1.1) |
|
||||
|------------|---------------|----------------------|
|
||||
| Org-scoped repo create | `POST /api/v1/orgs/{org}/repos` | Used for any new repos |
|
||||
| Native Pages | **None** | Serve `acdl-evidence` via raw file URLs (unchanged from v1.0) |
|
||||
| Environments API | **None**; act_runner ignores `environment:` | Model HITL gates via `workflow_dispatch` approval inputs (v1.0 D-013 pattern) — **refined in Phase 07** for the real pre-execution gate model |
|
||||
| `repository_dispatch` | Not supported | Cross-repo trigger via `workflow_dispatch` API (unchanged) |
|
||||
| Reusable workflows | Supported | `acdl/.gitea/workflows/pipeline.yml` via `uses: ...@<ref>` |
|
||||
| `id-token: write` / OIDC | **Not supported** (RESEARCH TARGET 1, conf 0.95). Gitea docs list `id-token` as an unsupported GitHub-only scope; open proposal go-gitea/gitea#33681; draft PR go-gitea/gitea#36988 unmerged. Even Gitea's own CI uses long-lived AWS keys (issue #37980). | **Spike waiver D-039:** per-run-rotated long-lived key (rotated after each run by `scripts/rotate_spike_key.sh`). Real OIDC deferred to v1.2, blocked on PR #36988. |
|
||||
| `actions/configure-aws-credentials` | Unusable without OIDC | Spike uses static AWS creds from a (rotated) Gitea Actions secret via the `aws-actions/configure-aws-credentials@v4` `access-key-id`/`secret-access-key` inputs, or plain `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` env vars. v1.2 switches to `role-to-assume` when OIDC lands. |
|
||||
|
||||
### Branch pinning rule (refined for W2.A)
|
||||
|
||||
- Dev/qa contracts reference the reusable workflow by **tag**
|
||||
(`@v1.1-spike`).
|
||||
- Prod-bound workflows reference by **SHA**; the platform CLI
|
||||
(`platform/cli/resolve-tag.ts`, Phase 07) resolves the current tag to its
|
||||
SHA. (Spike scope: the CLI is a stub; the real CLI lands in v1.2.)
|
||||
|
||||
### Verification toolchain
|
||||
|
||||
ACDL has no `package.json`. The verification gate substitutes:
|
||||
- **typecheck:** `terraform validate`, `python3 -m py_compile`, JSON Schema
|
||||
validation (`ajv` or `python -m jsonschema`) against `schemas/`.
|
||||
- **test:** per-phase `scripts/verify_phaseNN.sh` (Phase 06: archive integrity;
|
||||
Phase 07: schema validation + decision-resolution completeness; Phase 08:
|
||||
OIDC assume-role + state backend; Phase 09: IR + L1 + adapter `terraform
|
||||
plan`; Phase 10: end-to-end contract submission).
|
||||
- **build:** `terraform init` (real build for the spike).
|
||||
- See `PERSONAS.md` verification_toolchain.
|
||||
|
||||
## Build order (v1.1)
|
||||
|
||||
1. Phase 06 — archive demo, reorient repo.
|
||||
2. Phase 07 — finalize architecture v1.0; author schemas + designs.
|
||||
3. Phase 08 — AWS OIDC bootstrap (use temp key once, rotate).
|
||||
4. Phase 09 — IR + `l1-s3` + Terraform adapter → `terraform plan`.
|
||||
5. Phase 10 — `l2-static-asset` + contract→IR → end-to-end spike.
|
||||
6. COMPLETE gate — review → ship `v1.2.0` → audit.
|
||||
+70
-43
@@ -1,21 +1,22 @@
|
||||
---
|
||||
project: acdl
|
||||
milestone: v1.0
|
||||
milestone: v1.1
|
||||
generated_at: 2026-07-21
|
||||
generator: lead-developer
|
||||
verification_toolchain:
|
||||
typecheck: "bash -n scripts/**/*.sh modules/**/*.sh && python3 -m py_compile scripts/**/*.py"
|
||||
typecheck: "terraform validate && python3 -m py_compile platform/**/*.py && python3 -m jsonschema schemas/*.schema.json"
|
||||
test: "scripts/verify_phaseNN.sh"
|
||||
build: "no-op (no build step; bash + python stubs)"
|
||||
build: "terraform init"
|
||||
note: |
|
||||
ACDL has no package.json. The execute/verify/ship workflows substitute
|
||||
bash -n and python -m py_compile for npm run typecheck, a per-phase
|
||||
verify script for npm test, and treat npm run build as a no-op. This
|
||||
override is documented here as the single source of truth; the ci-*
|
||||
agents read PERSONAS.md before running verification commands.
|
||||
`terraform validate` + `python -m py_compile` + JSON Schema validation
|
||||
(`python -m jsonschema` or `ajv`) for npm run typecheck, a per-phase
|
||||
verify script for npm test, and `terraform init` for npm run build.
|
||||
This override is documented here as the single source of truth; the
|
||||
ci-* agents read PERSONAS.md before running verification commands.
|
||||
---
|
||||
|
||||
# ACDL — Persona Roster (project-level)
|
||||
# ACDL — Persona Roster (project-level, v1.1)
|
||||
|
||||
## Active personas
|
||||
|
||||
@@ -24,68 +25,94 @@ verification_toolchain:
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** (none)
|
||||
- **Constraints:** pragmatic, battle-tested defaults, no-cross-territory-edits
|
||||
- **Territory:** `.ciagent/**`, `scripts/verify_phase*.sh`, `README.md`, `.gitignore`
|
||||
- **Reason:** Owns CIAgent metadata and cross-phase verification scripts.
|
||||
- **Constraints:** pragmatic, battle-tested defaults, no-cross-territory-edits, vision-is-source-of-truth-for-why
|
||||
- **Territory:** `.ciagent/**`, `scripts/verify_phase*.sh`, `README.md`, `docs/**` (meta only — not architecture authoring), `.gitignore`
|
||||
- **Reason:** Owns CIAgent metadata, cross-phase verification scripts, and the v1.1 phase orchestration. Resolves the 11 open decisions (D-038) and arbitrates persona conflicts.
|
||||
|
||||
### backend-engineer
|
||||
- **Domain:** backend
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** gitea-actions, act_runner, bash, python, yaml
|
||||
- **Constraints:** no-cloud, no-ai, stub-only, hash-chain-must-be-deterministic, max-depth-5
|
||||
- **Territory:** `.gitea/workflows/**`, `scripts/**` (except `scripts/verify_phase*.sh`), `modules/l2/**/manifest.yaml`
|
||||
- **Reason:** Owns workflow YAML, core scripts (mock_executor, policy_checker, confidence_signal, evidence_writer, l3b_agent_stub), and L2 composition manifests.
|
||||
- **Frameworks:** python, json-schema, gitea-actions, act_runner, bash, yaml
|
||||
- **Constraints:** contract-schema-first, fail-fast-with-reason-codes, no-long-lived-credentials, severity-to-penalty-mapping-immutable
|
||||
- **Territory:** `platform/confidence_signal.py`, `platform/contract_resolver.py`, `platform/outbox/**`, `schemas/**` (contract + IR + PolicyCheckResult), `contracts/**` (sample contracts), `.gitea/workflows/**` (pipeline)
|
||||
- **Reason:** Owns the contract schema, contract→IR resolution, the confidence signal (6 inputs + severity mapping), the DynamoDB outbox writer, and the central pipeline workflow.
|
||||
|
||||
### infra-stub-engineer (custom)
|
||||
- **Domain:** backend
|
||||
### platform-engineer (custom)
|
||||
- **Domain:** infra
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** bash, yaml
|
||||
- **Constraints:** mock-only, echo-contract-from-D-007, sleep-1s-exit-0, substrate-agnostic, single-purpose
|
||||
- **Territory:** `modules/l1/**`
|
||||
- **Reason:** Created to own L1 stub modules (Phase 02) and their uniform mock_apply.sh behavior per D-007. Domain is backend (bash stubs) but territory is strictly L1 modules to keep L1/L2 concerns separated from workflow YAML.
|
||||
- **Frameworks:** terraform, aws-iam, aws-s3, aws-dynamodb, oidc, json-schema
|
||||
- **Constraints:** ir-is-substrate-agnostic, adapter-is-only-substrate-specific-code, state-in-s3+dynamodb-single-region, oidc-only-no-long-lived-keys (waiver D-034 for bootstrap), terraform-plan-only-in-spike
|
||||
- **Territory:** `adapters/terraform/**`, `modules-ir/**`, `terraform/**` (state backend, provider config), `platform/registry/**`
|
||||
- **Reason:** Owns the Target Stack IR, the L1/L2 IR-typed modules, the Terraform adapter, the AWS OIDC bootstrap, and the state backend. The IR is substrate-agnostic; the adapter is the only substrate-specific code (the binding constraint per §12).
|
||||
|
||||
### security-engineer (custom)
|
||||
- **Domain:** security
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** aws-iam, oidc, checkov, json-schema
|
||||
- **Constraints:** least-privilege, separation-of-duties-identity-distinctness, no-secrets-in-skill-markdown, audit-chain-extends-not-tears-up, critical-finding-hard-overrides-confidence
|
||||
- **Territory:** `platform/hitl_matrix_design.md`, `platform/audit_ledger_design.md`, `adapters/terraform/policy/**` (Checkov adapter → PolicyCheckResult), `platform/separation_of_duties.py`
|
||||
- **Reason:** Owns the HITL matrix design, separation-of-duties (DynamoDB identity-distinctness), the audit ledger design (S3 Object Lock + JWS + chain), and the Checkov→PolicyCheckResult adapter. Enforces the "Safety is Computed, Not Assumed" + "Audit truth lives outside the repository" vision tenets.
|
||||
|
||||
### frontend-engineer
|
||||
- **Domain:** frontend
|
||||
- **Active:** true
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** vanilla-js, dom-api, fetch-api
|
||||
- **Constraints:** no-frameworks, single-file, fetch-from-same-origin-raw-url, relative-url-for-audit-json
|
||||
- **Territory:** `evidence-ui/**` (the timeline UI; pushed to `acdl-evidence`)
|
||||
- **Reason:** Owns the evidence timeline UI (`index.html`). Carried over from v1.0; the UI continues to render the audit stream. The v1.1 spike writes events to the DynamoDB outbox; the UI continues to read `audit.json` published to `acdl-evidence`.
|
||||
|
||||
## Deactivated personas
|
||||
|
||||
### infra-stub-engineer (custom, v1.0 only)
|
||||
- **Domain:** backend
|
||||
- **Active:** false
|
||||
- **Reason:** Owned L1 stub modules (`modules/l1/**`) in the v1.0 demo. The demo is archived to `demo/` in Phase 06; real L1 modules (`modules-ir/l1/**`) are owned by platform-engineer (substrate-agnostic IR + Terraform adapter). The stub engineer is no longer needed.
|
||||
- **Phase-specific:** false (was v1.0)
|
||||
- **Territory (would have been):** `demo/modules/l1/**`
|
||||
|
||||
### data-engineer
|
||||
- **Domain:** data
|
||||
- **Active:** false
|
||||
- **Reason:** No persistence layer. ACDL state is flat JSON files (`audit.json`, `state.json`) written by bash/python scripts; no ORM, no migrations, no DB. Schema contracts live in `manifest.yaml` (owned by backend-engineer / infra-stub-engineer).
|
||||
- **Reason:** No ORM/persistence framework. The v1.1 outbox is DynamoDB but accessed via boto3 calls inside `platform/outbox/**` (owned by backend-engineer); the audit ledger is S3 Object Lock + JWS (owned by security-engineer). No schema-migration layer, no ORM, no data-engineer territory.
|
||||
- **Phase-specific:** false
|
||||
- **Frameworks:** (would have been: drizzle, prisma)
|
||||
- **Constraints:** (would have been: schema-first, type-safe-orm)
|
||||
- **Territory:** (would have been: `**/db/**`, `**/migrations/**`)
|
||||
|
||||
### frontend-engineer
|
||||
- **Domain:** frontend
|
||||
- **Active:** true # REACTIVATED for Phase 05 (evidence UI + dry run)
|
||||
- **Reason:** Phase 05 builds the vanilla-JS `index.html` timeline UI (REQ-14) and runs the 4 demo acts end-to-end dry run (REQ-15). Inactive for Phases 01-04 (no UI).
|
||||
- **Phase-specific:** true (this reactivation is for Phase 05 only; will be deactivated again after the milestone ships if the project continues)
|
||||
- **Frameworks:** vanilla-js, dom-api, fetch-api
|
||||
- **Constraints:** no-frameworks, single-file, fetch-from-same-origin-raw-url, relative-url-for-audit-json
|
||||
- **Territory:** `evidence-ui/**` (the source-of-truth `index.html` in the `acdl` repo; pushed to `acdl-evidence` by `run_demo.sh`)
|
||||
|
||||
## Phase-specific overrides
|
||||
|
||||
| Phase | Personas active | Reactivations / notes |
|
||||
|-------|-----------------|----------------------|
|
||||
| 01 repo-scaffolding | lead-developer, backend-engineer | infra-stub-engineer idle (no L1 work this phase) |
|
||||
| 02 l1-modules | lead-developer, backend-engineer, infra-stub-engineer | infra-stub-engineer owns L1 stubs |
|
||||
| 03 l2-modules-and-core-scripts | lead-developer, backend-engineer, infra-stub-engineer | backend-engineer owns core scripts + L2 manifests; infra-stub-engineer only updates L1 manifests if referenced |
|
||||
| 04 pipeline-and-approval-gates | lead-developer, backend-engineer | infra-stub-engineer idle; frontend-engineer still off |
|
||||
| 05 evidence-ui-and-demo-dry-run | lead-developer, backend-engineer, frontend-engineer | frontend-engineer REACTIVATED for `index.html` only; backend-engineer owns the dry-run script and audit.json wiring |
|
||||
| Phase | Personas active | Notes |
|
||||
|-------|------------------|-------|
|
||||
| 06 archive-demo-and-reorient | lead-developer, frontend-engineer (demo UI move only) | backend/platform/security idle |
|
||||
| 07 architecture-v1-finalization | lead-developer, backend-engineer (schemas), security-engineer (HITL/ledger/SoD), platform-engineer (IR) | frontend idle |
|
||||
| 08 aws-oidc-bootstrap | platform-engineer (lead), security-engineer (trust policy review) | backend/frontend idle |
|
||||
| 09 v1-spike-ir-and-l1-and-adapter | platform-engineer (lead), backend-engineer (IR schema co-author) | security/frontend idle |
|
||||
| 10 v1-spike-l2-and-contract-e2e | platform-engineer (L2 + adapter), backend-engineer (contract→IR + confidence + outbox), security-engineer (Checkov→PolicyCheckResult), frontend-engineer (evidence event surfaces in timeline) | Full roster |
|
||||
|
||||
## Domain priority (used by TaskDecomposer)
|
||||
|
||||
`coordination -> backend -> infra-stub-engineer -> frontend-engineer (Phase 05 only)`
|
||||
`coordination → security → platform → backend → frontend`
|
||||
|
||||
Rationale: in v1.1, the security/architecture commitments (IR, confidence,
|
||||
HITL, ledger, SoD) are the binding constraints; the platform layer
|
||||
materializes them; backend wires the pipeline; frontend surfaces the
|
||||
evidence. The spike's correctness depends on the security + platform layers
|
||||
being right before backend wiring.
|
||||
|
||||
## Conflict resolutions (lead-developer arbitration)
|
||||
|
||||
- `backend-engineer` vs `infra-stub-engineer` over `modules/l2/**/manifest.yaml`: backend-engineer owns L2 manifests; infra-stub-engineer owns L1 manifests. No overlap.
|
||||
- `backend-engineer` vs `frontend-engineer` over `acdl-evidence/index.html`: frontend-engineer owns the file in Phase 05; backend-engineer provides the `audit.json` schema contract (event shape) via `evidence_writer.py` and a `SCHEMA.md` note in ARCHITECTURE.md.
|
||||
- `lead-developer` vs any: lead-developer owns `.ciagent/**` and verification scripts; persona engineers do not edit CIAgent metadata.
|
||||
- `backend-engineer` vs `platform-engineer` over `schemas/ir.schema.json`: platform-engineer owns the IR (it is substrate-agnostic but infra-shaped); backend-engineer owns the contract schema and the contract→IR resolution (contract is the consumer surface). Co-authoring is expected; conflict goes to lead-developer.
|
||||
- `backend-engineer` vs `security-engineer` over `platform/confidence_signal.py`: security-engineer owns the severity→penalty mapping + critical-override semantics; backend-engineer owns the 6-input weighted sum + per-env thresholds. The confidence signal is co-owned; conflicts go to lead-developer.
|
||||
- `platform-engineer` vs `security-engineer` over `adapters/terraform/policy/**`: security-engineer owns the Checkov→PolicyCheckResult adapter (policy is a security concern); platform-engineer owns the Terraform adapter (substrate translation). No overlap.
|
||||
- `lead-developer` vs any: lead-developer owns `.ciagent/**` + `docs/**` meta + verification scripts; persona engineers do not edit CIAgent metadata or the vision/architecture source docs.
|
||||
|
||||
## Territory enforcement mode
|
||||
|
||||
`warn` — config.json has no `personas.territory_enforcement` field, so the default per execute.md is `warn`. Cross-territory edits are logged in the commit message but do not fail the task.
|
||||
`warn` — config.json has no `personas.territory_enforcement` field, so the
|
||||
default per execute.md is `warn`. Cross-territory edits are logged in the
|
||||
commit message but do not fail the task. The spike's small scope means
|
||||
co-authoring across territories is likely; `warn` keeps it frictionless.
|
||||
+417
-64
@@ -1,100 +1,453 @@
|
||||
---
|
||||
phase: 05
|
||||
name: evidence-ui-and-demo-dry-run
|
||||
milestone: v1.0
|
||||
phase: 6
|
||||
name: archive-demo-and-reorient
|
||||
milestone: v1.1
|
||||
milestone_type: feature
|
||||
status: planned
|
||||
requirements: [REQ-13, REQ-14, REQ-15]
|
||||
requirements: [] # Phase 06 introduces NO new REQ — it is repo hygiene (ROADMAP §Phase 06).
|
||||
must_haves:
|
||||
- "evidence-ui/index.html exists: single HTML file with inline CSS + JS, no external resources, no frameworks (D-032, REQ-14)"
|
||||
- "index.html fetches ./audit.json (relative URL) and renders events as a vertical timeline with stage color-coding (dev/qa/prod/finalize/genesis) + 12-char hash preview"
|
||||
- "scripts/run_demo.sh exists: simulates all 4 acts (Friction, Dev Self-Service, Citizen Developer, Safety Net) by calling the Phase 03 core scripts + evidence_writer.py + finalize_evidence.py; writes a final audit.json; uploads audit.json + evidence-ui/index.html to acdl-evidence main via the Gitea file-contents API (D-031/D-033)"
|
||||
- "scripts/run_demo.sh is idempotent: re-running overwrites both files on acdl-evidence and produces the same audit.json (deterministic hash chain)"
|
||||
- "Act 4 produces a 'dev rejected: POLICY_VIOLATION:PUBLIC_INGRESS' evidence event with score 0.40 (the Safety Net)"
|
||||
- "scripts/verify_phase05.sh passes: validates index.html structure (single file, inline, fetch call), runs run_demo.sh, fetches the raw audit.json + index.html URLs from acdl-evidence and confirms HTTP 200"
|
||||
- "demo/ contains the full v1.0 demo (modules/, scripts/, evidence-ui/, contracts/, contracts-repo/, .gitea/workflows/, ACDL_DEMO.md)"
|
||||
- "demo/scripts/run_demo.sh --no-upload exits 0 (regression: the archived demo still runs from demo/)"
|
||||
- "New top-level dirs exist and are empty-but-scaffolded with a .gitkeep: platform/, schemas/, adapters/, terraform/, modules-ir/"
|
||||
- "A new top-level scripts/ dir exists with scripts/verify_phase06.sh (v1.1 verify scripts live at top-level scripts/, NOT demo/scripts/)"
|
||||
- "README.md reflects the real platform (vision + architecture links, new layout); the v1.0 demo README content moves to demo/ACDL_DEMO.md (already there)"
|
||||
- ".gitignore updated to ignore runner-data/ (untracked demo runner artifact) if not already"
|
||||
- "No stray empty dirs left at repo root from the moves (contracts-repo/ etc.)"
|
||||
verification:
|
||||
typecheck: "bash -n scripts/*.sh && python3 -m py_compile scripts/*.py"
|
||||
test: "scripts/verify_phase05.sh"
|
||||
build: no-op
|
||||
typecheck: "bash -n demo/scripts/*.sh && python3 -m py_compile demo/scripts/*.py"
|
||||
test: "scripts/verify_phase06.sh # lives at TOP-LEVEL scripts/, not demo/scripts/"
|
||||
build: "no-op # Phase 06 is repo hygiene; terraform init is Phase 09+"
|
||||
---
|
||||
|
||||
# Phase 05 — evidence-ui-and-demo-dry-run PLAN
|
||||
# Phase 06 — archive-demo-and-reorient PLAN
|
||||
|
||||
## Goal
|
||||
|
||||
Build the vanilla-JS timeline UI and run the 4 demo acts as a local dry
|
||||
run that produces a real `audit.json` and publishes it (plus the UI) to
|
||||
`acdl-evidence` main. This is the milestone's capstone phase.
|
||||
Archive the complete v1.0 demo under `demo/` (preserve it as the intent
|
||||
reference per D-037), establish the new v1.1 repo layout
|
||||
(`platform/`, `schemas/`, `adapters/`, `terraform/`, `modules-ir/`), and
|
||||
rewrite `README.md` to reflect the real Agentic Cloud Delivery Platform.
|
||||
Verify the archived demo still runs end-to-end from `demo/` via
|
||||
`demo/scripts/run_demo.sh --no-upload` (regression gate).
|
||||
|
||||
This is **repo hygiene only** — no new code, no new REQ. It reorients the
|
||||
repo from "the v1.0 demo is the repo" to "the v1.0 demo is an archived
|
||||
artifact under `demo/`; the repo root is now the real platform's home."
|
||||
|
||||
## Requirements covered
|
||||
|
||||
- REQ-13: `acdl-evidence` is Pages-enabled and serves `audit.json` plus `index.html` (substituted by D-012: raw-URL 200 on both files)
|
||||
- REQ-14: `index.html` uses vanilla JS to fetch `audit.json` and render events as a timeline
|
||||
- REQ-15: All four demo acts reproduce deterministically in a dry run
|
||||
**None new.** Phase 06 carries no REQ-NN entry (ROADMAP §Phase 06:
|
||||
"Requirements: (no new REQ; repo hygiene)"). It is a structural
|
||||
prerequisite for Phase 07 (architecture-v1-finalization), which owns
|
||||
REQ-16..REQ-22.
|
||||
|
||||
## Waves (vertical slices, domain priority order)
|
||||
**Dependency:** the v1.0 demo must be complete and tagged. It is — tag
|
||||
`v1.1.0` exists (verified: `git tag` lists `v1.0.1`..`v1.0.5`, `v1.1.0`).
|
||||
All v1.0 phases shipped and audited PASS (ROADMAP §v1.0). The archive
|
||||
preserves the demo immutably; v1.0 tags are not rewritten (PROJECT.md
|
||||
operational parameter: "v1.0 tags preserved").
|
||||
|
||||
### Wave 1 — frontend-engineer (the UI)
|
||||
**No upstream phase dependency within v1.1** — Phase 06 is the first
|
||||
v1.1 phase. RESEARCH TARGET 10 (conf 0.90) provides the authoritative
|
||||
move list and confirms via static analysis that no path fixups are
|
||||
needed: all demo scripts resolve paths via `SCRIPT_DIR`/`REPO_ROOT`
|
||||
relative-to-script, which auto-adjust when the tree moves to `demo/`.
|
||||
|
||||
**Tasks:**
|
||||
## Waves
|
||||
|
||||
- **T-5.1** Create `evidence-ui/index.html` — single HTML file with inline `<style>` + `<script>`. The JS fetches `./audit.json` (relative URL), parses the JSON array, and renders a vertical timeline. Each event card shows: `seq` (badge), `ts` (timestamp), `stage` (color-coded chip: dev=blue, qa=yellow, prod=orange, finalize=green, genesis=gray, rejected=red), `event` text, and `hash.slice(0, 12) + "…"` (a 12-char preview). Includes a refresh button that re-fetches. Handles fetch failure with a "No audit data yet" message. No external resources (no CDN, no fetch libraries); vanilla JS only. The file is self-contained.
|
||||
Domain priority order from `PERSONAS.md`:
|
||||
`coordination → security → platform → backend → frontend`.
|
||||
|
||||
**Files owned:** `evidence-ui/index.html`
|
||||
Phase 06 active personas (PERSONAS.md "Phase-specific overrides"):
|
||||
**lead-developer** (coordination — owns the moves, the new layout, the
|
||||
README, and the verify script) + **frontend-engineer** (demo UI move
|
||||
confirmation only). Backend/platform/security are idle this phase.
|
||||
|
||||
**Commits:** one commit, `phase: 5, status: plan-as-execute, persona: frontend-engineer, task: T-5.1, requirements.covered: [REQ-14]`.
|
||||
Three waves, strictly ordered (each wave's tasks depend on the prior
|
||||
wave completing):
|
||||
|
||||
### Wave 2 — backend-engineer (the dry-run script)
|
||||
---
|
||||
|
||||
**Tasks:**
|
||||
### Wave 1 — lead-developer: file moves + new layout + README + verify script
|
||||
|
||||
- **T-5.2** Create `scripts/run_demo.sh` — the Phase 05 dry-run simulation. It:
|
||||
1. Accepts an optional `--no-upload` flag (for testing without hitting Gitea).
|
||||
2. Creates a clean working directory under `/tmp/acdl_demo_run/`; sets `AUDIT=/tmp/acdl_demo_run/audit.json`.
|
||||
3. Initializes the audit log: `python3 scripts/evidence_writer.py --stage genesis --event "audit log initialized" --audit "$AUDIT"`.
|
||||
4. **Act 1 — Friction:** write a single event `--stage dev --event "Act 1 Friction: manual 2-week deployment (legacy process)"`.
|
||||
5. **Act 2 — Developer Self-Service:** write `contracts/act2.yaml` with `stack: l2-commodity-price-feed`, `public-ingress: false`. Run `policy_checker.py` + `confidence_signal.py` + `mock_executor.sh`. Write events: `dev applied: l2-commodity-price-feed`, `qa approved`, `prod approved`, `finalize: audit.json committed`.
|
||||
6. **Act 3 — Citizen Developer:** feed an Issue body ("We need to ingest natural gas prices from Platts...") to `l3b_agent_stub.py -o contracts/act3.yaml`. Run the same pipeline as Act 2 against the generated contract. Write 4 events.
|
||||
7. **Act 4 — Safety Net:** write `contracts/act4.yaml` with `stack: l2-regulatory-reporting`, `public-ingress: true`. Run `policy_checker.py` (fails) + `confidence_signal.py` (score 0.40). Since score < 0.50, write `dev rejected: POLICY_VIOLATION:PUBLIC_INGRESS` and skip QA/Prod/Finalize.
|
||||
8. Print a summary of all events.
|
||||
9. If `--no-upload` is NOT set: call `python3 scripts/finalize_evidence.py --audit "$AUDIT"` to upload `audit.json` to `acdl-evidence`, then call `finalize_evidence.py --audit evidence-ui/index.html --path index.html --message "chore(ui): update index.html"` to upload the UI. (Reuses `finalize_evidence.py` with `--path` override for `index.html`.)
|
||||
10. Exit 0 if all 4 acts produced the expected evidence events; non-zero otherwise.
|
||||
The structural reorientation. All moves use `git mv` to preserve history.
|
||||
The v1.0 verify scripts move *with* `scripts/` into `demo/scripts/` (they
|
||||
are demo artifacts); the *new* v1.1 verify script lives at a *new*
|
||||
top-level `scripts/` dir (created fresh in this wave).
|
||||
|
||||
Cleanup: write contracts under `contracts/` (gitignored) so the working tree stays clean.
|
||||
#### T-6.1 — Move the v1.0 demo tree into `demo/`
|
||||
|
||||
**Files owned:** `scripts/run_demo.sh`
|
||||
- **Owner:** lead-developer (territory: `.ciagent/**`, `README.md`,
|
||||
`.gitignore`, top-level layout).
|
||||
- **Files owned:** `demo/` (new), everything moved into it.
|
||||
- **Commit message:**
|
||||
`phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.1`
|
||||
- **Commands to run verbatim** (cross-checked against RESEARCH.md
|
||||
TARGET 10's move list; verified the dirs exist and are tracked
|
||||
via `git ls-files`):
|
||||
|
||||
**Commits:** one commit, `phase: 5, status: plan-as-execute, persona: backend-engineer, task: T-5.2, requirements.covered: [REQ-13, REQ-15]`.
|
||||
```bash
|
||||
# From the repo root (/root/acdl). All moves via `git mv` to preserve history.
|
||||
# 1. Create the demo/ container.
|
||||
mkdir -p demo
|
||||
|
||||
### Wave 3 — lead-developer (verify script + traceability)
|
||||
# 2. Move the five demo dirs + the demo deck + the demo contracts-repo.
|
||||
git mv modules demo/modules
|
||||
git mv scripts demo/scripts # carries verify_phase01..05.sh (v1.0 demo verify scripts)
|
||||
git mv evidence-ui demo/evidence-ui
|
||||
git mv contracts demo/contracts # only holds examples/ (v1.0 sample contracts)
|
||||
git mv contracts-repo demo/contracts-repo # tracked: .gitea/workflows/{.gitkeep,issue-to-contract.yml}
|
||||
git mv .gitea demo/.gitea # carries workflows/{.gitkeep,pipeline.yml}
|
||||
git mv ACDL_DEMO.md demo/ACDL_DEMO.md # the v1.0 presentation deck (was untracked — `git add` it first)
|
||||
|
||||
**Tasks:**
|
||||
# 3. Handle the untracked demo runner artifact: do NOT git mv (it's untracked).
|
||||
# Move it out of the repo root so it doesn't linger as a stray dir.
|
||||
mv runner-data demo/runner-data # plain mv — not tracked; runner-data/.runner
|
||||
# (runner-data/ is added to .gitignore in T-6.4 so it stays a local artifact.)
|
||||
|
||||
- **T-5.3** Create `scripts/verify_phase05.sh`. Checks:
|
||||
1. `evidence-ui/index.html` exists, is a single file, contains `<style>` and `<script>` inline tags, contains `fetch('./audit.json'` (relative URL), no `https://` external resource references (no CDN).
|
||||
2. `scripts/run_demo.sh` is `bash -n` clean.
|
||||
3. Run `scripts/run_demo.sh --no-upload` and confirm:
|
||||
- It exits 0.
|
||||
- It produces a non-empty `audit.json` with at least 14 events (genesis + act1 + act2[4] + act3[4] + act4[1] = 11 minimum, but with markers it may be more — use `>= 11`).
|
||||
- The audit chain is valid (re-run the hash check).
|
||||
- The Act 4 event contains "POLICY_VIOLATION:PUBLIC_INGRESS".
|
||||
4. If `ACDL_GITEA_TOKEN` is set: run `scripts/run_demo.sh` (with upload), then curl the raw URLs for `audit.json` and `index.html` on `acdl-evidence` and confirm HTTP 200 + that the audit.json matches the local one (or at least parses as JSON with the expected number of events) + that index.html contains "ACDL Evidence" or "audit.json" reference.
|
||||
5. If `ACDL_GITEA_TOKEN` is NOT set: skip the upload check with a clear "SKIP (no token)" message; the dry-run + structural checks are sufficient.
|
||||
- **T-5.4** Update `.ciagent/REQUIREMENTS.md` (REQ-13/14/15 → covered pending VERIFY) and `.ciagent/ROADMAP.md` (Phase 05 → executing).
|
||||
# 4. Sanity: no empty stray dirs remain at repo root.
|
||||
# (git mv removes the source dir when it becomes empty; verify with `ls`.)
|
||||
```
|
||||
|
||||
**Files owned:** `scripts/verify_phase05.sh`, `.ciagent/REQUIREMENTS.md`, `.ciagent/ROADMAP.md`
|
||||
**Cross-check vs RESEARCH.md TARGET 10 move list:**
|
||||
- `modules/ → demo/modules/` ✓
|
||||
- `scripts/ → demo/scripts/` ✓ (carries v1.0 verify_phase01..05.sh — those
|
||||
are *demo* verify scripts; the v1.1 verify script is created in T-6.3
|
||||
at a *new* top-level `scripts/` dir)
|
||||
- `evidence-ui/ → demo/evidence-ui/` ✓
|
||||
- `contracts/ → demo/contracts/` ✓
|
||||
- `.gitea/workflows/{.gitkeep,pipeline.yml} → demo/.gitea/workflows/` ✓
|
||||
(achieved by moving the whole `.gitea/` dir)
|
||||
- `ACDL_DEMO.md → demo/ACDL_DEMO.md` ✓
|
||||
- `contracts-repo/ → demo/contracts-repo/` ✓ (tracked; confirmed via
|
||||
`git ls-files contracts-repo/` → `.gitea/workflows/.gitkeep` +
|
||||
`.gitea/workflows/issue-to-contract.yml`)
|
||||
- `runner-data/ → demo/runner-data/` ✓ (untracked; plain `mv`)
|
||||
|
||||
**Commits:** one per task, `phase: 5, status: plan-as-execute, persona: lead-developer, task: T-5.3/5.4`.
|
||||
**Subtlety (per task instructions):** the v1.1 verify scripts live at a
|
||||
*new* top-level `scripts/` dir (created in T-6.3), NOT inside `demo/scripts/`
|
||||
(which holds the v1.0 demo verify scripts `verify_phase01..05.sh`). This
|
||||
avoids colliding the v1.1 verification toolchain with the archived demo's.
|
||||
|
||||
## Wave ordering
|
||||
**Risk note (R-5 from RESEARCH.md):** static analysis found only
|
||||
`/tmp/...` temp-file writes in the demo scripts (e.g.
|
||||
`scripts/gitea_setup.sh`, `scripts/verify_phase01.sh`) — no source-root
|
||||
absolute paths. All demo scripts use `SCRIPT_DIR`/`REPO_ROOT`
|
||||
relative-to-script, which auto-resolve to `demo/` after the move. The
|
||||
regression check in T-6.3 / Wave 3 confirms this empirically.
|
||||
|
||||
- Wave 1 (frontend) builds the UI.
|
||||
- Wave 2 (backend) builds the dry-run script.
|
||||
- Wave 3 (lead-developer) verifies + traceability.
|
||||
#### T-6.2 — Scaffold the new v1.1 top-level dirs (empty, .gitkeep'd)
|
||||
|
||||
Wave 1 and Wave 2 can run in parallel (no file overlap), but per execute.md the domain priority is `coordination → backend → frontend → custom`. Here `frontend-engineer` and `backend-engineer` have no territory overlap, so they can run sequentially in priority order: backend first (Wave 2), then frontend (Wave 1) — but for clarity I'll keep Wave 1 = frontend, Wave 2 = backend (the UI is the visible artifact; the script needs to upload it). Actually, `run_demo.sh` references `evidence-ui/index.html`, so the UI must exist before the script is tested end-to-end. Order: Wave 1 (UI) → Wave 2 (script) → Wave 3 (verify).
|
||||
- **Owner:** lead-developer (territory: top-level layout).
|
||||
- **Files owned:** `platform/.gitkeep`, `schemas/.gitkeep`,
|
||||
`adapters/.gitkeep`, `terraform/.gitkeep`, `modules-ir/.gitkeep`.
|
||||
- **Commit message:**
|
||||
`phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.2`
|
||||
- **Commands:**
|
||||
|
||||
```bash
|
||||
# From the repo root. Five new empty-but-scaffolded dirs per ROADMAP §Phase 06.
|
||||
# These are populated in Phases 07–10; here they only need to exist + be tracked.
|
||||
for d in platform schemas adapters terraform modules-ir; do
|
||||
mkdir -p "$d"
|
||||
: > "$d/.gitkeep" # empty placeholder so git tracks the dir
|
||||
done
|
||||
git add platform/.gitkeep schemas/.gitkeep adapters/.gitkeep terraform/.gitkeep modules-ir/.gitkeep
|
||||
```
|
||||
|
||||
**Territory note (PERSONAS.md):** these dirs are owned in later phases
|
||||
by backend-engineer (`platform/confidence_signal.py`, `schemas/**`,
|
||||
`platform/outbox/**`), platform-engineer (`adapters/terraform/**`,
|
||||
`modules-ir/**`, `terraform/**`, `platform/registry/**`), and
|
||||
security-engineer (`platform/hitl_matrix_design.md`,
|
||||
`platform/audit_ledger_design.md`, `adapters/terraform/policy/**`). In
|
||||
Phase 06 they are *empty* — no territory conflict.
|
||||
|
||||
#### T-6.3 — Create the new top-level `scripts/` + write `scripts/verify_phase06.sh`
|
||||
|
||||
- **Owner:** lead-developer (territory: `scripts/verify_phase*.sh`).
|
||||
- **Files owned:** `scripts/.gitkeep` (or the verify script itself acts as
|
||||
the dir anchor), `scripts/verify_phase06.sh`.
|
||||
- **Commit message:**
|
||||
`phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.3`
|
||||
- **What `scripts/verify_phase06.sh` must assert** (the Phase 06 success
|
||||
criteria from ROADMAP, made executable):
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# scripts/verify_phase06.sh — Phase 06 archive regression + layout check.
|
||||
# Lives at TOP-LEVEL scripts/ (v1.1 verify scripts), NOT demo/scripts/.
|
||||
set -u
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
fail() { echo "FAIL: $*" >&2; exit 1; }
|
||||
ok() { echo "ok: $*"; }
|
||||
|
||||
# --- Check 1: demo/ contains the full v1.0 demo tree ---
|
||||
for d in demo/modules demo/scripts demo/evidence-ui demo/contracts \
|
||||
demo/contracts-repo demo/.gitea/workflows; do
|
||||
[ -d "$d" ] || fail "missing $d"
|
||||
done
|
||||
[ -f demo/ACDL_DEMO.md ] || fail "missing demo/ACDL_DEMO.md"
|
||||
[ -f demo/scripts/run_demo.sh ] || fail "missing demo/scripts/run_demo.sh"
|
||||
ok "demo/ contains the full v1.0 demo"
|
||||
|
||||
# --- Check 2: regression — the archived demo still runs from demo/ ---
|
||||
# run_demo.sh uses WORKDIR=/tmp/acdl_demo_run (absolute temp), so it
|
||||
# does not pollute the repo. --no-upload skips Gitea API calls.
|
||||
out=$(ACDL_GITEA_TOKEN= bash demo/scripts/run_demo.sh --no-upload 2>&1); rc=$?
|
||||
[ "$rc" -eq 0 ] || { echo "$out" >&2; fail "demo/scripts/run_demo.sh --no-upload exited $rc"; }
|
||||
ok "demo/scripts/run_demo.sh --no-upload exits 0"
|
||||
|
||||
# --- Check 3: new top-level dirs exist and are scaffolded ---
|
||||
for d in platform schemas adapters terraform modules-ir; do
|
||||
[ -d "$d" ] || fail "missing new top-level dir $d"
|
||||
[ -f "$d/.gitkeep" ] || fail "missing $d/.gitkeep"
|
||||
done
|
||||
ok "new top-level dirs exist: platform/ schemas/ adapters/ terraform/ modules-ir/"
|
||||
|
||||
# --- Check 4: no stray v1.0 dirs left at repo root ---
|
||||
for stray in modules evidence-ui contracts contracts-repo ACDL_DEMO.md; do
|
||||
[ -e "$stray" ] && fail "stray $stray left at repo root (should be under demo/)"
|
||||
done
|
||||
# .gitea/ at repo root is OK *only if* it's a new v1.1 workflow dir; in Phase 06
|
||||
# we moved the demo's .gitea/ to demo/.gitea/, so repo-root .gitea/ should NOT
|
||||
# exist yet (Phase 07+ may re-create it for the real pipeline).
|
||||
[ -e ".gitea" ] && fail "stray .gitea/ left at repo root (moved to demo/.gitea/)"
|
||||
ok "no stray v1.0 dirs at repo root"
|
||||
|
||||
# --- Check 5: README reflects the real platform ---
|
||||
grep -q "Agentic Cloud Delivery Platform" README.md || fail "README missing platform name"
|
||||
grep -q "demo/" README.md || fail "README does not reference the archived demo/"
|
||||
grep -qi "vision\|architecture" README.md || fail "README missing vision/architecture links"
|
||||
ok "README reflects the real platform (name + demo/ ref + vision/arch links)"
|
||||
|
||||
echo "Phase 06: ALL CHECKS PASS"
|
||||
```
|
||||
|
||||
**Note on `bash -n` / `py_compile` (typecheck gate):** the verify script
|
||||
itself is covered by `bash -n scripts/verify_phase06.sh`; the moved demo
|
||||
scripts are covered by `bash -n demo/scripts/*.sh` + `python3 -m py_compile
|
||||
demo/scripts/*.py` (the typecheck gate in the frontmatter). These run in
|
||||
Wave 3 before the full verify.
|
||||
|
||||
#### T-6.4 — Rewrite `README.md` + update `.gitignore`
|
||||
|
||||
- **Owner:** lead-developer (territory: `README.md`, `.gitignore`).
|
||||
- **Files owned:** `README.md`, `.gitignore`.
|
||||
- **Commit message:**
|
||||
`phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.4`
|
||||
- **`README.md` must contain:**
|
||||
- Project name: "ACDL — Agentic Cloud Delivery Platform".
|
||||
- One-line vision lift from `PROJECT.md` (consumers declare intent; the
|
||||
platform delivers safe production deployment through an agentic stack).
|
||||
- Links: `docs/vision.md` (the why), `docs/architecture.md` (the how),
|
||||
`.ciagent/PROJECT.md` (decisions), `.ciagent/ARCHITECTURE.md` (target
|
||||
architecture), `.ciagent/ROADMAP.md` (phase plan).
|
||||
- **New layout section** listing the top-level dirs and what each is for:
|
||||
- `platform/` — platform code (confidence signal, contract resolver,
|
||||
outbox, HITL/ledger designs) [populated Phase 07+].
|
||||
- `schemas/` — JSON Schemas (IR, PolicyCheckResult, contract) [Phase 07].
|
||||
- `adapters/` — substrate adapters (Terraform adapter in v1) [Phase 09].
|
||||
- `terraform/` — state backend + provider config [Phase 08+].
|
||||
- `modules-ir/` — IR-typed L1/L2 modules (`l1-s3`, `l2-static-asset`)
|
||||
[Phase 09–10].
|
||||
- `scripts/` — v1.1 verify scripts (`verify_phaseNN.sh`).
|
||||
- `demo/` — the archived v1.0 executive demo (tag `v1.1.0`); runs locally
|
||||
via `demo/scripts/run_demo.sh --no-upload`. Intent reference; not the
|
||||
platform.
|
||||
- `.ciagent/` — CIAgent metadata (plans, decisions, personas, roadmap).
|
||||
- `docs/` — upstream vision + architecture sources.
|
||||
- A "Status" line: v1.1 active — architecture finalization + v1 spike.
|
||||
v1.0 demo complete (tag `v1.1.0`), archived under `demo/`.
|
||||
- **No** v1.0 demo run instructions in the root README — point at
|
||||
`demo/ACDL_DEMO.md` for the demo deck and `demo/scripts/run_demo.sh`.
|
||||
|
||||
- **`.gitignore` update:**
|
||||
- Add `runner-data/` (the untracked demo runner artifact; moved to
|
||||
`demo/runner-data/` in T-6.1, but any future local runner registration
|
||||
should be ignored at the repo root too).
|
||||
- Keep existing entries (`__pycache__/`, `*.pyc`, `*.pyo`, `.env*`,
|
||||
`state.json`, `audit.json`, `*.tmp`, `.DS_Store`).
|
||||
- The existing `.gitignore` (read) is:
|
||||
```
|
||||
__pycache__/
|
||||
*.pyc
|
||||
*.pyo
|
||||
.env
|
||||
.env.*
|
||||
state.json
|
||||
audit.json
|
||||
*.tmp
|
||||
.DS_Store
|
||||
```
|
||||
Append `runner-data/` (and optionally `demo/runner-data/` for
|
||||
completeness).
|
||||
|
||||
---
|
||||
|
||||
### Wave 2 — frontend-engineer: confirm `demo/evidence-ui/` moved cleanly
|
||||
|
||||
The UI is frozen as a demo artifact (D-033: relative fetch URL). No code
|
||||
changes unless the move broke the fetch path — which static analysis says
|
||||
it cannot (the UI is a single static `index.html` with a relative URL to
|
||||
`audit.json` on the `acdl-evidence` raw URL). This wave is a confirmation,
|
||||
not a build.
|
||||
|
||||
#### T-6.5 — Confirm `demo/evidence-ui/index.html` integrity + fetch path
|
||||
|
||||
- **Owner:** frontend-engineer (territory: `evidence-ui/**`, now
|
||||
`demo/evidence-ui/**`).
|
||||
- **Files owned:** `demo/evidence-ui/index.html` (read-only confirmation;
|
||||
edit only if the fetch URL is broken, which it is not per D-033).
|
||||
- **Commit message (if no edit needed — confirmation only, may be a
|
||||
no-op commit or folded into Wave 3's verify):**
|
||||
`phase: 6, status: plan-as-execute, persona: frontend-engineer, task: T-6.5`
|
||||
- **Checks the frontend-engineer performs:**
|
||||
1. `demo/evidence-ui/index.html` exists and is byte-identical to the
|
||||
pre-move file (git history preserved via `git mv`).
|
||||
2. The fetch URL inside `index.html` is relative (per D-033) — e.g.
|
||||
`fetch('audit.json')` or a raw-URL reference to `acdl-evidence`.
|
||||
It must NOT reference a repo-root-relative path that broke when
|
||||
moved under `demo/`.
|
||||
3. If (and only if) `scripts/verify_phase06.sh` (run in Wave 3) reports
|
||||
the UI fetch path broken, the frontend-engineer patches
|
||||
`demo/evidence-ui/index.html`'s fetch URL to be relative. Per D-033
|
||||
and RESEARCH TARGET 10 finding #5, **no patch is expected** — this
|
||||
is a confirm-only task.
|
||||
- **No code changes expected.** If a patch is needed, it is a one-line
|
||||
fetch-URL fix and the commit message above applies.
|
||||
|
||||
---
|
||||
|
||||
### Wave 3 — lead-developer: run the full Phase 06 verification
|
||||
|
||||
The regression gate. Runs only after Wave 1 (moves done) and Wave 2
|
||||
(frontend confirmation done).
|
||||
|
||||
#### T-6.6 — Run `scripts/verify_phase06.sh` + typecheck gate
|
||||
|
||||
- **Owner:** lead-developer (territory: `scripts/verify_phase*.sh`).
|
||||
- **Files owned:** none (execution-only).
|
||||
- **Commit message (if any fixup is needed; otherwise this is a verify
|
||||
run, not a commit):**
|
||||
`phase: 6, status: plan-as-execute, persona: lead-developer, task: T-6.6`
|
||||
- **Commands:**
|
||||
|
||||
```bash
|
||||
# Typecheck gate (from frontmatter):
|
||||
bash -n demo/scripts/*.sh && echo "demo shell scripts: syntax ok"
|
||||
python3 -m py_compile demo/scripts/*.py && echo "demo python scripts: compile ok"
|
||||
bash -n scripts/verify_phase06.sh && echo "verify_phase06.sh: syntax ok"
|
||||
|
||||
# Test gate (the Phase 06 regression):
|
||||
bash scripts/verify_phase06.sh
|
||||
# Expected output: "Phase 06: ALL CHECKS PASS"
|
||||
# This runs demo/scripts/run_demo.sh --no-upload internally (Check 2).
|
||||
```
|
||||
|
||||
**On failure:** if `demo/scripts/run_demo.sh --no-upload` fails, the
|
||||
cause is an undetected absolute path in a demo script (R-5 residual
|
||||
0.10). Fix the offending path in `demo/scripts/*.sh` (make it
|
||||
`SCRIPT_DIR`/`REPO_ROOT`-relative) and re-run. If the UI fetch path is
|
||||
broken, Wave 2's frontend-engineer patches `demo/evidence-ui/index.html`.
|
||||
|
||||
**On pass:** Phase 06 is complete. The phase-completion commit +
|
||||
`v1.1.0`-style phase tag (or the v1.1 phase-tagging convention) is
|
||||
created by the execute workflow, not this plan.
|
||||
|
||||
---
|
||||
|
||||
## Wave ordering (dependency graph)
|
||||
|
||||
```
|
||||
Wave 1 (T-6.1, T-6.2, T-6.3, T-6.4) lead-developer
|
||||
│ moves + scaffold + verify script + README
|
||||
▼
|
||||
Wave 2 (T-6.5) frontend-engineer
|
||||
│ confirm demo/evidence-ui/ moved cleanly (no code change expected)
|
||||
▼
|
||||
Wave 3 (T-6.6) lead-developer
|
||||
run scripts/verify_phase06.sh (regression + layout + README checks)
|
||||
```
|
||||
|
||||
- **Wave 1 → Wave 2:** the UI must be moved before it can be confirmed.
|
||||
- **Wave 2 → Wave 3:** the frontend confirmation must precede the full
|
||||
verify (so any UI fetch-path patch is in place before
|
||||
`verify_phase06.sh` runs the demo end-to-end).
|
||||
- **Within Wave 1:** T-6.1 (moves) must precede T-6.2 (new dirs — they
|
||||
would collide if `scripts/` still held the v1.0 verify scripts when
|
||||
T-6.3 creates the new top-level `scripts/`). T-6.3 (verify script) can
|
||||
be authored in parallel with T-6.2 but cannot *run* until T-6.1 + T-6.2
|
||||
are committed. T-6.4 (README) is independent of T-6.1..T-6.3 in content
|
||||
but should land in the same wave so the repo is coherent after Wave 1.
|
||||
|
||||
**Strict sub-ordering within Wave 1:** T-6.1 → T-6.2 → T-6.3 (T-6.3
|
||||
creates the new top-level `scripts/` which must not exist during T-6.1's
|
||||
`git mv scripts demo/scripts`). T-6.4 (README + .gitignore) may be done
|
||||
in parallel with T-6.2/T-6.3.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on Phases 01-04 (all core scripts, workflows, and the acdl-evidence repo must exist).
|
||||
- This is the last phase in the milestone. After Phase 05 ships, the COMPLETE gate runs: review → ship(milestone v1.1.0) → audit.
|
||||
- **v1.0 demo complete + tagged** — satisfied (tag `v1.1.0` present;
|
||||
ROADMAP §v1.0 "complete").
|
||||
- **No upstream v1.1 phase dep** — Phase 06 is the first v1.1 phase.
|
||||
- **RESEARCH.md TARGET 10** — the authoritative move list + the static
|
||||
analysis confirming no path fixups are needed (conf 0.90; R-5 residual
|
||||
is the only open risk, caught by the Wave 3 regression check).
|
||||
- **PERSONAS.md** — Phase 06 active roster: lead-developer + frontend-
|
||||
engineer (demo UI move only). backend/platform/security idle.
|
||||
|
||||
## Tasks summary
|
||||
|
||||
| Task | Wave | Owner | Territory | Commit message tag |
|
||||
|------|------|-------|-----------|--------------------|
|
||||
| T-6.1 | 1 | lead-developer | `demo/` (new), moved dirs | `task: T-6.1` |
|
||||
| T-6.2 | 1 | lead-developer | `platform/`, `schemas/`, `adapters/`, `terraform/`, `modules-ir/` (new empty) | `task: T-6.2` |
|
||||
| T-6.3 | 1 | lead-developer | top-level `scripts/verify_phase06.sh` (new) | `task: T-6.3` |
|
||||
| T-6.4 | 1 | lead-developer | `README.md`, `.gitignore` | `task: T-6.4` |
|
||||
| T-6.5 | 2 | frontend-engineer | `demo/evidence-ui/index.html` (confirm-only) | `task: T-6.5` |
|
||||
| T-6.6 | 3 | lead-developer | (execution: `scripts/verify_phase06.sh`) | `task: T-6.6` |
|
||||
|
||||
All commit messages follow the format:
|
||||
`phase: 6, status: plan-as-execute, persona: <name>, task: T-6.N`
|
||||
|
||||
## Risks (specific to Phase 06)
|
||||
|
||||
1. **R-5 (RESEARCH, residual 0.10): undetected absolute path in a demo
|
||||
script.** Mitigation: Wave 3 runs `demo/scripts/run_demo.sh --no-upload`
|
||||
and asserts exit 0. A failure is caught there and fixable in-phase by
|
||||
making the offending path `SCRIPT_DIR`/`REPO_ROOT`-relative. The
|
||||
typecheck gate (`bash -n demo/scripts/*.sh`) catches syntax issues
|
||||
but not path issues — only the runtime regression catches those.
|
||||
|
||||
2. **`contracts-repo/` is tracked and moves with `git mv`.** Verified:
|
||||
`git ls-files contracts-repo/` returns
|
||||
`.gitea/workflows/.gitkeep` + `.gitea/workflows/issue-to-contract.yml`.
|
||||
It is a demo artifact (the v1.0 `acdl-contracts` mirror used by
|
||||
`verify_phase04.sh`). Moving it to `demo/contracts-repo/` is correct;
|
||||
`demo/scripts/verify_phase04.sh` references it via the
|
||||
`ROOT`-relative path `contracts-repo/.gitea/workflows/...` which
|
||||
auto-resolves to `demo/contracts-repo/...` after the move (ROOT =
|
||||
parent of `demo/scripts/` = `demo/`).
|
||||
|
||||
3. **`runner-data/` is untracked.** It is moved with plain `mv` (not
|
||||
`git mv`) and gitignored. If a future runner registration recreates it
|
||||
at the repo root, `.gitignore` (updated in T-6.4) keeps it untracked.
|
||||
|
||||
4. **`ACDL_DEMO.md` was untracked** (verified: `git status` shows
|
||||
`?? ACDL_DEMO.md`). `git mv` on an untracked file will fail; the
|
||||
executor must `git add` it first (or use `mv` + `git add demo/ACDL_DEMO.md`).
|
||||
The command list in T-6.1 uses `git mv ACDL_DEMO.md demo/ACDL_DEMO.md`
|
||||
— if git rejects it as untracked, fall back to:
|
||||
`mv ACDL_DEMO.md demo/ACDL_DEMO.md && git add demo/ACDL_DEMO.md`.
|
||||
|
||||
5. **`verify_phase05.sh` has an anti-stray check** (lines 159-160:
|
||||
`if [ -d "$ROOT/contracts" ]; then fail "contracts/ directory left in
|
||||
repo root"`). After the move, `ROOT` for `demo/scripts/verify_phase05.sh`
|
||||
is `demo/`, and `demo/contracts/` *does* exist — so this check would
|
||||
fail if the v1.0 verify script is re-run from `demo/`. This is
|
||||
expected: the v1.0 verify scripts are *archived demo artifacts*, not
|
||||
re-run after Phase 06. The v1.1 verify script
|
||||
(`scripts/verify_phase06.sh`) supersedes them. No action needed beyond
|
||||
documenting that v1.0 verify scripts are not re-run post-archive.
|
||||
+206
-73
@@ -2,94 +2,227 @@
|
||||
|
||||
## 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.
|
||||
Consumers declare intent; the platform delivers safe production
|
||||
deployment through an agentic stack. The platform absorbs two frictions:
|
||||
the cognitive load of getting the infrastructure right, and the
|
||||
operational work of getting the change to production safely.
|
||||
|
||||
## Objective
|
||||
Source of truth for **why**: `docs/vision.md`.
|
||||
Source of truth for **how**: `docs/architecture.md` + `.ciagent/ARCHITECTURE.md`.
|
||||
Where the two conflict, the vision wins.
|
||||
|
||||
Build a runnable demo (Linux + GitHub/Gitea Actions) that walks executives through four acts:
|
||||
## North Star
|
||||
|
||||
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.
|
||||
A merged change progresses through lower environments end-to-end without a
|
||||
platform engineer joining a thread, approving a ticket, or manually
|
||||
triggering a stage gate. A non-technical consumer ships a production
|
||||
deployment by declaring intent — without authoring a workflow, a
|
||||
configuration file, or a Terraform module. Every production change is
|
||||
traceable to a human attestation and an immutable evidence stream.
|
||||
|
||||
## Core Tenets (from `docs/vision.md`)
|
||||
|
||||
1. **Operations are Declared, Not Executed.** Consumers define what they
|
||||
need; the platform reconciles, provisions, and progresses.
|
||||
2. **The Delivery Lifecycle is a Sovereign Boundary.** The platform
|
||||
governs infra and delivery; it does not penetrate upstream product/SDLC.
|
||||
Integration is only through validated, published contracts.
|
||||
3. **Lower Environments are Autonomous; Higher Environments are Attested.**
|
||||
Dev = zero-touch agentic. QA/prod/dr = deliberate human attestation, not
|
||||
rubber stamps.
|
||||
4. **Safety is Computed, Not Assumed.** Every action produces a measurable,
|
||||
explainable confidence signal. The signal is the platform's certified
|
||||
answer to "is this safe to proceed?"
|
||||
5. **Infrastructure is Consumed, Not Maintained.** Compute is abstract,
|
||||
containerized, or serverless. No node/OS/bare-metal lifecycle.
|
||||
6. **Two Consumer Surfaces, One Platform.** Technical developers (L3A) and
|
||||
non-technical consumers (L3B) converge on the same contract schema, the
|
||||
same policy envelope, and the same evidence stream.
|
||||
|
||||
## Domain Boundaries
|
||||
|
||||
- **In scope:** environment progression; cloud resource lifecycle; operational
|
||||
security and observability NFRs; policy enforcement; immutable audit
|
||||
lineage; confidence frameworks; two consumer surfaces (developer + agentic).
|
||||
- **Out of scope:** application business logic; IDE workflows; product
|
||||
backlog / sprint planning; compute requiring node-level or OS-level management.
|
||||
- **Interface:** upstream systems integrate through a strict contract
|
||||
boundary. The platform validates, enriches with operational standards,
|
||||
and reconciles the target state.
|
||||
|
||||
## Objective for Milestone v1.1
|
||||
|
||||
Finalize the architecture to v1.0 (resolve all 11 open design decisions in
|
||||
`docs/architecture.md` §13) and prove the locked commitments with one
|
||||
end-to-end v1 implementation spike:
|
||||
|
||||
- **One L1 module** (`l1-s3`) — substrate-agnostic, IR-typed interface.
|
||||
- **One L2 thin-composition** (`l2-static-asset`) — references the L1.
|
||||
- **Terraform adapter** — compiles the IR to a real `terraform plan`
|
||||
against AWS via OIDC (no long-lived credentials, per §12.5).
|
||||
- **One contract submission** → contract→IR resolution →
|
||||
`terraform plan` → PolicyCheckResult (Checkov) → confidence signal →
|
||||
evidence event to the DynamoDB outbox.
|
||||
|
||||
The spike validates the architecture's claim that the IR-shaped commitments
|
||||
do not require a polyglot mess (`docs/architecture.md` §14, step 2).
|
||||
|
||||
## Milestone v1.1 Phases
|
||||
|
||||
| Phase | Name | Goal |
|
||||
|-------|------|------|
|
||||
| 06 | archive-demo-and-reorient | Move the v1.0 demo (`modules/`, `scripts/`, `evidence-ui/`, `contracts/`, demo workflows) to `demo/`; establish the new repo layout (`platform/`, `schemas/`, `adapters/`, `terraform/`, `modules-ir/`); rewrite README. |
|
||||
| 07 | architecture-v1-finalization | Resolve the 11 open decisions → architecture v1.0. Author IR JSON Schema, PolicyCheckResult schema, contract schema, confidence-signal spec, HITL matrix, outbox/ledger design under `schemas/` + `platform/`. |
|
||||
| 08 | aws-oidc-bootstrap | One-shot use of a temporary long-lived key (waiver D-034) to create an IAM role + OIDC trust policy for the act_runner, an S3 state bucket, and a DynamoDB lock table. Rotate the key. Verify the runner assumes the role via OIDC with no long-lived secret. |
|
||||
| 09 | v1-spike-ir-and-l1-and-adapter | Target Stack IR; one real L1 (`l1-s3`) with IR-typed interface; L1 registry; Terraform adapter (IR → Terraform var/output + `terraform plan`) running against AWS via OIDC. |
|
||||
| 10 | v1-spike-l2-and-contract-e2e | One L2 thin-composition (`l2-static-asset`) referencing `l1-s3`; contract schema + contract→IR resolution; one end-to-end contract submission → `terraform plan` → Checkov → confidence signal → evidence event to outbox. Verify the IR commitments hold. |
|
||||
|
||||
Milestone COMPLETE gate: review → ship `v1.2.0` (feature milestone, next
|
||||
minor per ship.md) → audit.
|
||||
|
||||
## 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.
|
||||
### v1.0 (Prior milestone — the demo)
|
||||
|
||||
### 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.
|
||||
Status: complete. Tag `v1.1.0`. All REQ-01..15 satisfied by the stub-driven
|
||||
executive demo. See `REQUIREMENTS.md` §v1 and the prior decisions table
|
||||
appendix below. The demo is **archived** to `demo/` in Phase 06.
|
||||
|
||||
### 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).
|
||||
### v1.1 (Active milestone — architecture finalization + v1 spike)
|
||||
|
||||
New requirements REQ-16..REQ-2x — see `REQUIREMENTS.md` §v1.1. Summary:
|
||||
|
||||
- **REQ-16:** Architecture finalized to v1.0 (11 open decisions resolved).
|
||||
- **REQ-17:** Target Stack IR defined as JSON Schema; substrate-agnostic.
|
||||
- **REQ-18:** PolicyCheckResult normalized schema defined; Checkov adapter.
|
||||
- **REQ-19:** Six-input confidence signal specified with per-env thresholds
|
||||
(dev 0.50 / qa 0.75 / prod 0.90 / dr 0.95) and severity→penalty mapping.
|
||||
- **REQ-20:** Tiered audit ledger design (S3 Object Lock 7-yr + DynamoDB
|
||||
outbox, RPO=0, JWS detached signatures, `prev_event_hash` chain).
|
||||
- **REQ-21:** Full 8-concern HITL matrix + separation-of-duties design
|
||||
(CODEOWNERS + DynamoDB identity-distinctness).
|
||||
- **REQ-22:** Contract schema (JSON Schema draft 2020-12) with per-env
|
||||
mandatory/optional inputs and `profile: agentic` marker for L3B.
|
||||
- **REQ-23:** AWS OIDC bootstrap (IAM role + trust policy for act_runner);
|
||||
the long-lived key is used once then rotated (waiver D-034).
|
||||
- **REQ-24:** One real L1 module (`l1-s3`) with an IR-typed interface.
|
||||
- **REQ-25:** One real L2 thin-composition (`l2-static-asset`) referencing
|
||||
`l1-s3`.
|
||||
- **REQ-26:** Terraform adapter compiles the IR to a real `terraform plan`
|
||||
against AWS via OIDC; state in S3 + DynamoDB.
|
||||
- **REQ-27:** One end-to-end contract submission → contract→IR resolution →
|
||||
`terraform plan` → Checkov → confidence signal → evidence event to outbox.
|
||||
- **REQ-28:** Spike verification proves the IR-shaped commitments hold (no
|
||||
polyglot mess; the adapter is the only substrate-specific code).
|
||||
|
||||
## 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.
|
||||
- **Forge:** Gitea at `https://git.cloudinit.dev`, org `continuous-intelligence`.
|
||||
- **CI runtime:** act_runner / Gitea Actions (reuses GitHub Actions workflow YAML).
|
||||
- **Cloud:** AWS via OIDC federation. **Long-lived credentials are forbidden**
|
||||
(§12.5). The v1.1 spike uses a temporary long-lived key **once** to bootstrap
|
||||
OIDC (waiver D-034), then rotates it.
|
||||
- **Substrate:** Terraform adapter in v1 (the only adapter). L1/L2 are
|
||||
substrate-agnostic in shape; the adapter is the only substrate-specific code.
|
||||
- **State:** S3 (state files) + DynamoDB (locking), single-region in v1.
|
||||
- **Environments:** dev (autonomous) → qa (QA HITL) → prod (SRE HITL) → dr
|
||||
(SRE HITL). **Staging does not exist** (Path A locked).
|
||||
- **Compute:** abstract / containerized / serverless. No VMs, bare metal, OS
|
||||
lifecycle.
|
||||
- **Autonomy:** Full. Escalation hooks: deploy, delete_data, merge_to_main.
|
||||
|
||||
## Anti-Goals (from `docs/vision.md` §7)
|
||||
|
||||
- Not an upstream development platform (no product backlogs, IDE, code authorship).
|
||||
- Not a general-purpose AI (autonomy is narrow, bounded by policy envelopes).
|
||||
- Not a legacy infrastructure bridge (no VMs/bare metal/OS).
|
||||
- Not a permissive delivery highway (no escape hatches past confidence or HITL).
|
||||
- Not a mutable audit log (VCS history ≠ regulatory evidence).
|
||||
|
||||
## 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.
|
||||
- The `acdl` repo exists at the org root. `acdl-contracts` and
|
||||
`acdl-evidence` exist from the v1.0 demo and continue as the developer
|
||||
surface and the audit-timeline host respectively.
|
||||
- `docs/vision.md` and `docs/architecture.md` (v0.2) are the upstream
|
||||
vision/architecture sources, pulled from `origin/main` at the start of v1.1.
|
||||
- The v1.0 demo (tag `v1.1.0`) is the reference of intent — it proved the
|
||||
shape (L1/L2/contract/confidence/evidence/HITL) on stubs. v1.1 replaces the
|
||||
stubs with the real platform substrate.
|
||||
|
||||
## Key Decisions
|
||||
## Key Decisions (v1.1)
|
||||
|
||||
Carries forward the still-valid v1.0 decisions (see appendix). New v1.1
|
||||
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 |
|
||||
| D-011 | Single-project mode explicitly enforced via `config.json mode: "single"` overriding `projects[]` length signal | run.md Step 0 reads `projects[]` length as multi-project trigger; explicit flag disambiguates | No `project:` prefix in commits or branches |
|
||||
| D-012 | Gitea has no native Pages — serve `acdl-evidence` via raw file URLs (`/raw/branch/main/...`) and a CORS note in ARCHITECTURE.md | Research confirms Gitea has no `[pages]` section | Demo can render `index.html` via raw URL without server-side Pages config |
|
||||
| D-013 | Gitea has no environments API and ignores `jobs.<id>.environment` — model QA/Prod gates as `workflow_dispatch` approval inputs (D-004 fallback) | Research confirms `environment:` blocks are ignored by act_runner | Approval gates become dispatch inputs; "environments" become workflow job names + optional branch protection on `qa`/`prod` branches |
|
||||
| D-014 | Cross-repo triggering uses the `workflow_dispatch` Gitea API (POST `/actions/workflows/{id}/dispatches`) from inside a step instead of `repository_dispatch` | Gitea Actions does not support `repository_dispatch` | Issue-trigger workflow calls the main pipeline via authenticated dispatch from a step |
|
||||
| D-015 | New repos `acdl-contracts` and `acdl-evidence` use `default_branch: "main"` with `auto_init: true` | Matches Gitea `DEFAULT_BRANCH=main`; required for the default branch to exist before any push | Reusable-workflow `uses:` references still pin `acdl` workflows to `@milestone/v1.0-initial` |
|
||||
| D-016 | Pages placeholder for Phase 01 is a minimal HTML stub (`<title>ACDL Evidence</title>` + "evidence stream coming soon"); full UI deferred to Phase 05 | Phase 01 success criterion is "Pages returns 200 with placeholder index.html" but Gitea has no Pages | Raw-URL HTTP 200 against `index.html` substitutes for the Pages check; full timeline UI built in Phase 05 |
|
||||
| D-017 | Each L1 `manifest.yaml` declares a single `inputs:` map of named string keys with descriptions; no nested types (substrate-agnostic, max-depth-1) | REQ-02/03 say "declared inputs"; spec forbids composition and cloud-specific types | Uniform, parseable schema that Phase 03's `mock_executor.sh` can read with python+yaml |
|
||||
| D-018 | L1 `mock_apply.sh` reads its own `manifest.yaml` for self-identification but ignores the input values (uniform stub per D-007) | D-007 mandates a literal echo + 1s sleep + exit 0; inputs are declared for traceability, not consumed | Predictable evidence events + clean separation from Phase 03 where L2s pass inputs to L1s |
|
||||
| D-019 | The 8 L1 names are fixed per REQ-02: `l1-eks-fargate`, `l1-iam-role`, `l1-lambda`, `l1-api-gateway`, `l1-eventbridge`, `l1-sqs`, `l1-s3`, `l1-cloudwatch` | REQ-02 literal | Phase 02 enumerates them exactly; no naming freedom |
|
||||
| D-020 | L2 `manifest.yaml` schema: `name`, `kind: l2`, `description`, `l1s:` (list of `{name, inputs: map}` entries). L2 references L1s by name (no path); inputs are string maps per L1 manifest declarations | REQ-04 says L2 "composes L1s"; REQ-05 caps depth at 5 (L2→L1 is depth 1) | mock_executor.sh reads `l1s:` and invokes each L1's `mock_apply.sh` |
|
||||
| D-021 | `contract.yaml` schema: `stack` (L2 name), `inputs` (string map for the L2's top-level params), optional `public-ingress: bool` (the policy violation key per REQ-07) | REQ-07 cites `public-ingress: true` as the forbidden key; REQ-08's confidence signal keys off policy pass/fail | Single flat schema drives both policy_checker and the mock_executor |
|
||||
| D-022 | `mock_executor.sh` writes `state.json` with shape `{"l2": "<name>", "l1s": [{"name":"...","applied":true,"exit_code":0}], "contract": <contract.yaml parsed>}` to the cwd; idempotent (overwrites) | REQ-06 says "writes state.json" but does not specify shape | Deterministic, parseable; Phase 05's evidence UI can include it in the audit trail |
|
||||
| D-023 | `evidence_writer.py` appends events to `audit.json` (a JSON array of event objects). Each event: `{"seq": N, "ts": <iso8601>, "stage": "dev|qa|prod|finalize", "event": "<string>", "prev_hash": "<sha256>", "hash": "<sha256 of canonical json of this event with hash field empty>"}`. The genesis event has `prev_hash: "GENESIS"` and `seq: 0` | D-005 mandates hash-chained ledger; canonical JSON for deterministic hashing | Visible tamper-evidence without overengineering; Phase 05 UI reads the array |
|
||||
| D-024 | `confidence_signal.py` reads `contract.yaml`, calls `policy_checker.py` (as a subprocess or import), returns base 0.90 on pass and 0.40 with reason code on policy failure; prints `{"score": 0.90|0.40, "reason": "<POLICY_VIOLATION:...|>"}` to stdout; exit 0 always | REQ-08 literal: base 0.90, drops to 0.40, gate ≥ 0.50 | Deterministic JSON output for the pipeline to consume |
|
||||
| D-025 | `policy_checker.py` reads `contract.yaml`, fails with exit code 1 and stdout `POLICY_VIOLATION:PUBLIC_INGRESS` if `public-ingress: true`; otherwise exits 0 with stdout `POLICY_PASS` | REQ-07 literal | Single source of policy truth; called by confidence_signal and the pipeline directly |
|
||||
| D-026 | `l3b_agent_stub.py` reads Issue body text from argv[1] (or stdin if no argv), applies the D-008 keyword map, writes a `contract.yaml` to stdout (or to `-o <path>`). Output contract uses the D-021 schema with `stack:` set to the mapped L2 name and a fixed `inputs:` map per L2 | D-008 + Act 3 example; L3B must produce the same contract format as L3A | Deterministic keyword parser; no external APIs |
|
||||
| D-027 | Phase 04 models the pipeline as TWO Gitea Actions workflows: (1) `acdl/.gitea/workflows/pipeline.yml` — `on: workflow_call` + `on: workflow_dispatch` (so it can be both called by the contracts-repo trigger AND manually re-dispatched for approvals); (2) `acdl-contracts/.gitea/workflows/issue-to-contract.yml` — `on: issues [opened]`. Approval gates are implemented as separate workflow_dispatch inputs (`approve_qa: bool`, `approve_prod: bool`) on the pipeline workflow, since Gitea ignores `environment:` blocks (D-013) | Gitea Actions has no environment reviewers, no `repository_dispatch`, no native approval UI | Pipeline can be re-dispatched by a human at each gate; the workflow_dispatch API call from a step (D-014) drives cross-repo triggering |
|
||||
| D-028 | The pipeline workflow runs all 4 stages (dev, qa-gate, prod-gate, finalize) in a single workflow run, with each gate job checking a workflow_dispatch input (`approve_qa`/`approve_prod`). When the input is false (the default), the gate job fails with a clear "awaiting approval" message; the human re-dispatches with `approve_qa=true` to advance. State (state.json, audit.json, contract ref) is passed via workflow artifacts (upload/download between jobs) because Gitea Actions artifacts work the same as GitHub Actions | Gitea Actions supports `actions/upload-artifact` and `actions/download-artifact`; the alternative is committing state between jobs, which is heavier | Deterministic, observable pipeline; artifacts keep the audit trail within one run |
|
||||
| D-029 | The finalize step commits `audit.json` to `acdl-evidence` main via the Gitea file-contents API (POST `/repos/{owner}/{repo}/contents/{path}` with the base64 content + a commit message referencing the pipeline run id), exactly like Phase 01's `gitea_setup.sh` does for `index.html`. It uses `${GITEA_TOKEN}` (a repo secret) for auth | D-012 raw-URL approach requires the file to be on main; the API is the only way to put it there from a workflow step | The evidence timeline (Phase 05 UI) fetches the raw URL after finalize completes |
|
||||
| D-030 | The issue-to-contract workflow in `acdl-contracts` checks out `l3b_agent_stub.py` from the `acdl` repo (pinned to `@milestone/v1.0-initial` per the branch-pin rule), parses the Issue body, commits `contract.yaml` to a new branch `contract/<issue-number>` on `acdl-contracts`, then dispatches the pipeline workflow on the `acdl` repo via `curl POST /actions/workflows/<id>/dispatches` with `inputs: {contract-ref: contract/<issue-number>}` (D-014). The pipeline workflow checks out `acdl-contracts` at that ref to read the contract | Gitea Actions cannot trigger across repos without an explicit API call; the branch carries the contract ref | Reproducible Act 3: Issue → contract.yaml → pipeline run with the same contract as Act 2 |
|
||||
| D-031 | Phase 05 "dry run" = a local bash script (`scripts/run_demo.sh`) that simulates the full pipeline by calling the core scripts in sequence + writing evidence events via `evidence_writer.py` + uploading `audit.json` to `acdl-evidence` via `finalize_evidence.py`. It does NOT use act_runner (no runner is registered in this environment). It exercises all 4 acts: (1) Friction — a static "manual 2-week" log entry; (2) Developer Self-Service — a valid `contract.yaml` for `l2-commodity-price-feed`, full pipeline (dev→qa→prod→finalize), all evidence events; (3) Citizen Developer — an Issue body, `l3b_agent_stub.py` produces the contract, identical pipeline; (4) Safety Net — a malicious `public-ingress: true` contract for `l2-regulatory-reporting`, dev rejects with confidence < 0.50, rejection visible in the timeline | The spec says "4 scripted acts reproduce deterministically in a dry run"; without a runner, the bash simulation IS the deterministic reproduction | The same `audit.json` shape is produced as a real pipeline run would produce, so the `index.html` UI renders the timeline identically |
|
||||
| D-032 | `index.html` (vanilla JS) is committed to the `acdl` repo at `evidence-ui/index.html` as the source of truth, and pushed to `acdl-evidence` main by `scripts/run_demo.sh` (via the file-contents API) alongside `audit.json`. The UI fetches `audit.json` from the same raw-URL origin (D-012). It renders events as a vertical timeline with `seq`, `ts`, `stage` (color-coded), `event` text, and a truncated `hash` per event. No frameworks; one HTML file with inline CSS + JS | D-012 raw-URL approach; the UI must be a single file (no separate JS/CSS) for simplicity; vanilla JS per REQ-14 | The UI loads in any browser by visiting the raw URL; it fetches the sibling `audit.json` and renders |
|
||||
| D-033 | The `audit.json` raw URL on `acdl-evidence` main is the single source of truth for the timeline. `run_demo.sh` writes the final `audit.json` (after all 4 acts) and the final `index.html` in two API calls. Re-running `run_demo.sh` overwrites both (idempotent). The UI's fetch URL is relative (`./audit.json`) so the same `index.html` works against any raw-URL origin | D-012 + D-029; relative URL avoids hardcoding the host | Deterministic re-run; UI always reflects the latest audit |
|
||||
| D-034 | Temporary long-lived AWS key (waiver) used once in Phase 08 to bootstrap OIDC trust; rotated immediately after | §12.5 forbids long-lived creds; OIDC needs one bootstrapping `aws iam` call before the runner can assume a role | Spike achieves real `terraform plan` against AWS without violating the locked target after bootstrap |
|
||||
| D-035 | Milestone version = `v1.1` (feature), ship tag `v1.2.0` | Real platform is a breaking reframing of the demo, but treated as the next incremental milestone per user choice; ship.md: feature milestone → next minor | Tag `v1.2.0` on milestone COMPLETE |
|
||||
| D-036 | Spike picks `l1-s3` + `l2-static-asset` | Simplest real AWS resource (no IAM/network deps); smallest real `terraform plan`; proves the IR + adapter end-to-end | Spike scope fixed |
|
||||
| D-037 | Demo archived to `demo/` (not deleted) | Preserves the working v1.0 demo as intent reference; new platform layout under `platform/`, `schemas/`, `adapters/`, `terraform/`, `modules-ir/` | No churn on demo code; clean separation |
|
||||
| D-038 | Open decisions resolved in "accept recommendations + decide rest" mode | User-locked mode: accept architecture's stated recommendations (W1.A, W1.B, W2.A, BA.A); lead-developer decides the remaining 8 (W3.D, W3.E, BA.B, BA.C, BA.D, BA.E, BA.F, OpenTofu timing) with rationale | Architecture reaches v1.0 in Phase 07 |
|
||||
| D-039 | Spike-only waiver: per-run-rotated long-lived AWS key. OIDC federation deferred to v1.2, blocked on go-gitea/gitea#36988. | **RESEARCH TARGET 1 verdict (conf 0.95):** Gitea Actions does NOT support `id-token: write` / OIDC token issuance as of Gitea 1.27.x / gitea-runner v2.1.0. GitHub's OIDC pattern is not portable. The waiver satisfies §12.5's *intent* (no persistent long-lived key) for the spike: the key is rotated after each run by `scripts/rotate_spike_key.sh`. v1.2 implements real OIDC when the Gitea PR merges. | Spike achieves real `terraform plan` against AWS without a *persistently* long-lived key; real OIDC is a v1.2 deliverable |
|
||||
| D-040 | The 6 confidence-signal inputs are: policy (0.30), validation (0.25), freshness (0.10), source (0.15), history (0.10), nfrs (0.10). Weights frozen for v1, tuned in v1.2 alongside thresholds (BA.B). | Architecture §8 locks "six canonical inputs" but does not enumerate them; RESEARCH TARGET 6 chose the platform-computable subset present in every environment (incl. dev). | Confidence signal (Phase 10) has a concrete input enumeration |
|
||||
| D-041 | Spike audit ledger = v1.0 hash chain + DynamoDB outbox + `acdl-evidence` mirror. S3 Object Lock (compliance mode, 7-yr) + JWS (platform KMS key, quarterly rotation) + daily checkpoints are v1.2 build-out, authored as design in Phase 07. | REQ-20 is "design authored," not "implemented." The spike proves the outbox write path; the regulatory ledger is v1.2. | Spike scope stays bounded; REQ-20 satisfied by the Phase 07 design doc |
|
||||
| D-042 | HITL approver identity in Gitea = `gitea.actor` of the `workflow_dispatch` run that sets `approve_qa=true`/`approve_prod=true`/`approve_dr=true`. Separation-of-duties reads `approver_qa` from the DynamoDB outbox and compares to the prod-dispatch `gitea.actor`. | Gitea has no Environments API (re-confirmed in RESEARCH); `gitea.actor` is the only approval-identity signal. | SoD design (Phase 07) is concrete for the Gitea forge |
|
||||
| D-043 | Tag/naming compliance deferred for the spike: the Checkov adapter emits a single `SKIPPED` PolicyCheckResult (`ruleId: ACDL_TAG_NAMING`, `severity: info`) so the confidence policy input is non-empty. Custom Checkov YAML rule lands in v1.2. | Checkov has no built-in tag-presence check; a custom rule in the spike is scope creep. | Spike's policy input is non-empty without a custom-rule dependency |
|
||||
| D-044 | DynamoDB outbox = `PAY_PER_REQUEST`; PK `contractId`, SK `eventType#eventTs`, TTL `expire_at` = now + 365d. No separate async worker/DLQ in the spike (RTO = workflow re-run); v1.2 outbox worker + DLQ is a Phase 07 design artifact. | On-demand is zero-cost-at-idle for the spike's single dev submission. | Spike outbox is minimal; v1.2 worker design authored in Phase 07 |
|
||||
| D-045 | Runner tooling: `runs-on: ubuntu-latest`; install `terraform` via HashiCorp apt repo (pin `1.9.*`), `checkov` via pip (pin `>=3.2,<4`, `--break-system-packages`). Neither is pre-installed on the default runner image. | RESEARCH TARGET 2; pinning avoids mid-spike version drift. | Phase 09/10 workflows have a concrete setup step |
|
||||
| D-046 | `act_runner` → `gitea-runner` rename: Phase 07 updates docs to use the current name `gitea-runner` (renamed 2026-04 in gitea/runner#850). | RESEARCH TARGET 1 + R-4: naming drift between v1.0 docs and the current runner. | Docs reflect the current binary name |
|
||||
|
||||
### Open-decision resolutions (Phase 07 deliverable — recorded here for traceability)
|
||||
|
||||
| ID | Question | Resolution |
|
||||
|---|---|---|
|
||||
| W1.A | AI-refinement trigger | **Accept recommendation.** Joint condition: N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in last 6 months AND Infra & Ops unilateral override. |
|
||||
| W1.B | Multi-stack edge case rule | **Accept recommendation.** Permitted only for (a) DR-region mirror, (b) time-boxed experimental stack with TTL ≤ 30d, (c) explicit Infra & Ops approval with `multiStack.justification`. |
|
||||
| W2.A | Tag mutability for prod | **Accept recommendation (Path B).** Tag for dev/qa, SHA for prod. Platform CLI resolves tag→SHA for prod-bound workflows. Justified by the "Audit truth lives outside the repository" bet. |
|
||||
| BA.A | Initial L3B skill catalog | **Accept recommendation.** 5 skills: web API, worker, scheduled job, static asset, basic observability bootstrap. Addition criteria: (a) reviewable for sensitive data, (b) expressible as a single contract submission, (c) documented use case. |
|
||||
| W3.D | L1/L2 standard versioning | **Decided.** Semver: interface → MAJOR, behavior → MINOR, lifecycle → PATCH (same as the v1.0 demo D-rule, lifted to the real platform). Pin model: L2 contracts pin L1 by `name@semver`; the resolver picks the highest compatible. Evolution: MAJOR bumps require a new registry entry (immutable publication); old entry enters a 12-month deprecation window. |
|
||||
| W3.E | Schema mandatory vs optional inputs | **Decided.** Per-env mandatory table: dev requires `stack` + `environment`; qa adds `validation.e2eSuite` + `validation.loadTest`; prod adds `runbook` + `dashboard` + `oncall`; dr adds `drDrillRef`. `inputs` map is always optional. `profile: agentic` fields (`naturalLanguageIntent`, `confidenceAtSubmission`, `agentTrace`) optional everywhere. |
|
||||
| BA.B | Confidence threshold tuning | **Decided.** Starting thresholds frozen for v1. Tuning begins in v1.2: track FP/FN per environment quarterly; override authority = Infra & Ops + SRE joint sign-off; any override is itself a confidence-event in the audit stream. |
|
||||
| BA.C | On-call / operational ownership | **Decided.** Platform on-call = Infra & Ops rotation. Escalation: L3A/L3B halt → platform on-call pager (Sev2); consumer-visible outage → consumer on-call (Sev1) with platform on-call support. Consumer on-call relationship is contractual, defined at onboarding (BA.E). |
|
||||
| BA.D | Cost / capacity governance | **Decided.** Cloud cost owner = Infra & Ops FinOps. Per-contract consumption reported monthly. Runaway spend: hard halt at 120% of contract-declared budget envelope via the confidence signal (cost is one of the 6 inputs); override = FinOps + SRE joint sign-off. |
|
||||
| BA.E | Consumer onboarding | **Decided.** Two paths: developer (L3A) — `getting-started` walks through contract schema + central pipeline template; citizen developer (L3B) — onboarding grants a scoped agent + skill catalog, no workflow authoring. Both end in a sandbox dev submission that must pass the confidence gate before the consumer is promoted. |
|
||||
| BA.F | Cross-platform evolution | **Decided.** The contract schema, IR, PolicyCheckResult, confidence signal, and audit stream are portable (substrate- and forge-agnostic). Forge-specific code: workflow YAML, OIDC trust, CODEOWNERS, Environments. A second forge (e.g., GitLab) requires a forge adapter + a workflow-template translator; no change to L1/L2/IR/confidence/audit. |
|
||||
| Q1.3 | OpenTofu timing | **Decided (deferred).** Not in v1 or v1.1. The substrate abstraction (§12) makes OpenTofu a future adapter, not an architecture change. Revisit when an OpenTofu adapter is requested; no version committed. |
|
||||
|
||||
## Appendix — Prior milestone (v1.0 demo) decisions
|
||||
|
||||
The v1.0 demo (tag `v1.1.0`) carried decisions D-001..D-033. They governed
|
||||
the stub-driven executive demo and remain valid **for the archived demo
|
||||
under `demo/`**. They are **superseded** by the v1.1 decisions above for the
|
||||
real platform. Full text preserved in git history at tag `v1.1.0`.
|
||||
|
||||
## Operational parameters (CLARIFY auto-resolution, full autonomy)
|
||||
|
||||
Resolved at the CLARIFY stage to unblock planning. None require user
|
||||
sign-off (autonomy = full; all within locked constraints).
|
||||
|
||||
| Parameter | Value | Rationale |
|
||||
|---|---|---|
|
||||
| AWS region | `us-east-1` | Default; matches v1.0 demo references; single-region in v1 (§12.3) |
|
||||
| Terraform state bucket | `acdl-tfstate-<account-id>-us-east-1` | Namespaced by account id to avoid collision; region-suffixed |
|
||||
| Terraform lock table | `acdl-tflock` | DynamoDB; single-region v1 |
|
||||
| OIDC IAM role | `acdl-act-runner-role` | Assumed by the act_runner via web-identity |
|
||||
| OIDC trust subject | `repo:continuous-intelligence/acdl:ref:refs/heads/main` (+ phase branches) | Least-privilege; refined in Phase 08 |
|
||||
| Spike L1 (`l1-s3`) inputs | `bucket_name: string`, `region: string` | Minimal S3 interface per §2 |
|
||||
| Spike L2 (`l2-static-asset`) | thin-composition referencing `l1-s3` only; depth 1 | Smallest real plan per D-036 |
|
||||
| Spike contract | `contracts/spike.yaml`: `stack: l2-static-asset`, `environment: dev`, `inputs: { bucket_name: acdl-spike-bucket, region: us-east-1 }` | One end-to-end submission (REQ-27) |
|
||||
| Spike `terraform` command | `plan` only | `apply` is out of scope (Out of Scope table); HITL-gated in v1.2 |
|
||||
| Checkov ruleset (spike) | the 4 L2 checks (secrets-in-plaintext, public ingress, IAM wildcard, KMS key reference) + tag/naming | §3 + §12.4; Kyverno/OPA deferred |
|
||||
| v1.0 tags preserved | `v1.0.1`..`v1.0.5`, `v1.1.0` retained | Immutability; demo archive does not rewrite history |
|
||||
| Next ship tag | `v1.2.0` | Feature milestone → next minor per ship.md (D-035) |
|
||||
|
||||
### Items deferred to RESEARCH (not clarifications)
|
||||
|
||||
- **Gitea/act_runner OIDC support** — does act_runner emit an OIDC
|
||||
`id-token`? Determines whether real-AWS plan is achievable in this
|
||||
environment or whether a spike-only waiver is needed. Highest-priority
|
||||
research target.
|
||||
- **Terraform + Checkov availability on the runner image** — install in the
|
||||
workflow if missing.
|
||||
- **`actions/configure-aws-credentials` action on act_runner** — if
|
||||
unavailable, fall back to `aws sts assume-role-with-web-identity` from a
|
||||
step.
|
||||
@@ -35,7 +35,42 @@
|
||||
|
||||
(None — v1 covers the complete demo.)
|
||||
|
||||
## Clarifications (Phase 01)
|
||||
## v1.1 (Active milestone — architecture finalization + v1 spike)
|
||||
|
||||
### Category: Architecture Finalization
|
||||
- **REQ-16:** Architecture reaches v1.0 — all 11 open decisions in `docs/architecture.md` §13 are resolved and recorded in `PROJECT.md` (W1.A, W1.B, W2.A, W3.D, W3.E, BA.A–F, OpenTofu timing).
|
||||
- **REQ-17:** Target Stack IR is defined as a JSON Schema under `schemas/ir.schema.json`; substrate-agnostic (resources, relationships, composition max-depth-5, policy hooks).
|
||||
- **REQ-18:** `PolicyCheckResult` normalized schema is defined under `schemas/policy_check_result.schema.json`; a Checkov adapter translates Checkov JSON to this schema.
|
||||
- **REQ-19:** Six-input confidence signal is specified under `platform/confidence_signal.py` with per-env thresholds (dev 0.50 / qa 0.75 / prod 0.90 / dr 0.95) and severity→penalty mapping (critical=hard override, high=-0.2, medium=-0.05, low=-0.01, info=0.0).
|
||||
- **REQ-20:** Tiered audit ledger design is authored: S3 Object Lock (compliance mode, 7-yr) + DynamoDB outbox (RPO=0, JWS detached signatures, `prev_event_hash` chain, daily checkpoints).
|
||||
- **REQ-21:** Full 8-concern HITL matrix + separation-of-duties design is authored (CODEOWNERS routing + DynamoDB identity-distinctness check; pre-execution gate model; 1d warn / 2d freeze timeout).
|
||||
- **REQ-22:** Contract schema (JSON Schema draft 2020-12) is defined under `schemas/contract.schema.json` with per-env mandatory/optional inputs (W3.E) and `profile: agentic` marker for L3B fields.
|
||||
|
||||
### Category: AWS OIDC Bootstrap
|
||||
- **REQ-23:** AWS auth bootstrap + state backend for the spike: an S3 state bucket + DynamoDB lock/outbox table + an IAM user with a minimal scoped policy (S3 + DynamoDB + plan-only). The temporary long-lived key is used once (waiver D-034) then rotated via `scripts/rotate_spike_key.sh` after each spike run (D-039). **Real OIDC federation is deferred to v1.2** — Gitea Actions does not support `id-token: write` (RESEARCH TARGET 1, conf 0.95), blocked on go-gitea/gitea#36988.
|
||||
|
||||
### Category: v1 Spike — IR, L1, Adapter
|
||||
- **REQ-24:** One real L1 module `l1-s3` exists under `modules-ir/l1/l1-s3/` with an IR-typed interface (typed inputs/outputs/NFRs) registered in the L1 registry.
|
||||
- **REQ-25:** One real L2 thin-composition `l2-static-asset` exists under `modules-ir/l2/l2-static-asset/` referencing `l1-s3` only (depth 1, within max-depth-5).
|
||||
- **REQ-26:** The Terraform adapter (`adapters/terraform/`) compiles the IR-typed L1 interface to Terraform `variable`/`output` blocks and the L2 thin-composition tree to a Terraform root module; it emits a real `terraform plan` against AWS via OIDC; state is stored in S3 + DynamoDB.
|
||||
|
||||
### Category: v1 Spike — End-to-End
|
||||
- **REQ-27:** One end-to-end contract submission (`contracts/spike.yaml` for `l2-static-asset`) flows through: contract schema validation → contract→IR resolution → `terraform plan` (real AWS) → Checkov `PolicyCheckResult` → confidence signal → evidence event written to the DynamoDB outbox.
|
||||
- **REQ-28:** Spike verification (`scripts/verify_phase10.sh`) proves the IR-shaped commitments hold: the adapter is the only substrate-specific code; no polyglot mess; the L1 content, contract YML, and thin-composition tree are substrate-agnostic.
|
||||
|
||||
## Out of Scope (v1.1)
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Full HITL matrix wiring (qa/prod/dr) | Spike is dev-only (`terraform plan`); HITL wiring is v1.2. |
|
||||
| Kyverno + OPA policy engines | Spike uses Checkov only; Kyverno/OPA are v1.2. |
|
||||
| MCP skill catalog + real L3B agent | L3B spike = a single stub contract submission; the 5-skill catalog is v1.2. |
|
||||
| GitOps reconciler (ArgoCD/Flux) | v1.2. |
|
||||
| Multi-region state / outbox | Single-region in v1 (§9, §12.3). |
|
||||
| Prod/dr environments | v1.2. |
|
||||
| Terraform `apply` (real provisioning) | Spike runs `plan` only; `apply` is gated by HITL in v1.2. |
|
||||
|
||||
## Clarifications (Phase 01, v1.0 — retained for history)
|
||||
|
||||
| REQ | Original criterion | Clarified criterion (effective) | Decision |
|
||||
|-----|--------------------|----------------------------------|----------|
|
||||
@@ -43,7 +78,7 @@
|
||||
| REQ-10 | "Pages returns 200 with placeholder `index.html`" on `acdl-evidence` | Gitea has no Pages; substitute: an HTTP GET against the raw file URL `https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html` returns 200 with the placeholder HTML body | D-012, D-016 |
|
||||
| REQ-10 | "`qa` and `prod` environments exist on `acdl-contracts`" | Gitea has no environments API and ignores `environment:` blocks; substitute: the reusable workflow defines `qa-gate` and `prod-gate` jobs gated by `workflow_dispatch` approval inputs (D-004 fallback); a `qa` and `prod` branch may be created on `acdl-contracts` as a visible stand-in for environments | D-013 |
|
||||
|
||||
## Out of Scope
|
||||
## Out of Scope (v1.0 demo — retained for history)
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
@@ -55,6 +90,8 @@
|
||||
|
||||
## Traceability
|
||||
|
||||
### v1.0 (prior — demo)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-01 | 1 | complete (v1.0.1) |
|
||||
@@ -69,6 +106,24 @@
|
||||
| REQ-10 | 4 | complete (v1.0.4) |
|
||||
| REQ-11 | 3 | complete (v1.0.3) |
|
||||
| REQ-12 | 4 | complete (v1.0.4) |
|
||||
| REQ-13 | 5 | covered (pending VERIFY) |
|
||||
| REQ-14 | 5 | covered (pending VERIFY) |
|
||||
| REQ-15 | 5 | covered (pending VERIFY) |
|
||||
| REQ-13 | 5 | complete (v1.0.5) |
|
||||
| REQ-14 | 5 | complete (v1.0.5) |
|
||||
| REQ-15 | 5 | complete (v1.0.5) |
|
||||
|
||||
### v1.1 (active — architecture finalization + v1 spike)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-16 | 07 | pending |
|
||||
| REQ-17 | 07 | pending |
|
||||
| REQ-18 | 07 | pending |
|
||||
| REQ-19 | 07 | pending |
|
||||
| REQ-20 | 07 | pending |
|
||||
| REQ-21 | 07 | pending |
|
||||
| REQ-22 | 07 | pending |
|
||||
| REQ-23 | 08 | pending |
|
||||
| REQ-24 | 09 | pending |
|
||||
| REQ-25 | 10 | pending |
|
||||
| REQ-26 | 09 | pending |
|
||||
| REQ-27 | 10 | pending |
|
||||
| REQ-28 | 10 | pending |
|
||||
File diff suppressed because it is too large
Load Diff
+78
-3
@@ -2,7 +2,18 @@
|
||||
|
||||
## 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.
|
||||
- **v1.0 (demo):** complete — tag `v1.1.0`, 2026-07-21. All 5 phases shipped + audited PASS.
|
||||
- **v1.1 (active):** architecture finalization + v1 spike. 5 phases (06–10).
|
||||
- **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
|
||||
|
||||
@@ -49,11 +60,75 @@ Five-phase breakdown to take ACDL from empty repo to a reproducible 4-act execut
|
||||
|
||||
### 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:** executing
|
||||
- **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.
|
||||
- Act 4: malicious `public-ingress: true` contract halts in Dev with confidence < 0.50 and a visible rejection reason on the timeline.
|
||||
|
||||
---
|
||||
|
||||
## v1.1 (Active — architecture finalization + v1 spike)
|
||||
|
||||
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` covers the real platform's first materialization. Ship tag at
|
||||
milestone COMPLETE: `v1.2.0` (feature milestone, next minor per ship.md).
|
||||
|
||||
### 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:** pending
|
||||
- **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:** pending
|
||||
- **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:** pending
|
||||
- **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:** pending
|
||||
- **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.
|
||||
@@ -4,7 +4,7 @@
|
||||
{
|
||||
"slug": "acdl",
|
||||
"name": "Agentic Cloud Delivery Platform",
|
||||
"milestone": "v1.0",
|
||||
"milestone": "v1.1",
|
||||
"status": "specify"
|
||||
}
|
||||
],
|
||||
|
||||
+2
-1
@@ -6,4 +6,5 @@ __pycache__/
|
||||
state.json
|
||||
audit.json
|
||||
*.tmp
|
||||
.DS_Store
|
||||
.DS_Store
|
||||
runner-data/
|
||||
@@ -1,55 +1,52 @@
|
||||
# ACDL — Agentic Cloud Delivery Platform
|
||||
|
||||
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.
|
||||
Consumers declare intent; the platform delivers safe production deployment
|
||||
through an agentic stack — automatically, safely, and with a complete audit
|
||||
trail. A merged change progresses through lower environments end-to-end
|
||||
without a platform engineer joining a thread; a non-technical consumer ships
|
||||
a production deployment by declaring intent, without authoring a workflow,
|
||||
a configuration file, or a Terraform module.
|
||||
|
||||
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.
|
||||
- **Vision** (the why): [`docs/vision.md`](docs/vision.md)
|
||||
- **Architecture** (the how): [`docs/architecture.md`](docs/architecture.md)
|
||||
- **Decisions**: [`.ciagent/PROJECT.md`](.ciagent/PROJECT.md)
|
||||
- **Target architecture**: [`.ciagent/ARCHITECTURE.md`](.ciagent/ARCHITECTURE.md)
|
||||
- **Phase plan**: [`.ciagent/ROADMAP.md`](.ciagent/ROADMAP.md)
|
||||
|
||||
## Four acts
|
||||
## Status
|
||||
|
||||
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/Gitea 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.
|
||||
- **v1.1 (active):** architecture finalization + v1 spike. Finalize the
|
||||
architecture to v1.0 (resolve the 11 open design decisions) and prove the
|
||||
locked commitments with one end-to-end implementation spike
|
||||
(`l1-s3` + `l2-static-asset` + Terraform adapter → real `terraform plan`
|
||||
against AWS).
|
||||
- **v1.0 demo (complete, archived):** tag `v1.1.0`. The 30-minute
|
||||
stub-driven executive demo is preserved under `demo/` as the intent
|
||||
reference; it is not the platform.
|
||||
|
||||
## Repositories
|
||||
## Repository layout
|
||||
|
||||
All under the `continuous-intelligence` Gitea org at
|
||||
`https://git.cloudinit.dev`:
|
||||
| Path | Purpose | Populated |
|
||||
|------|---------|-----------|
|
||||
| `platform/` | Platform code: confidence signal, contract resolver, outbox, HITL/ledger designs | Phase 07+ |
|
||||
| `schemas/` | JSON Schemas: IR, PolicyCheckResult, contract | Phase 07 |
|
||||
| `adapters/` | Substrate adapters (Terraform adapter in v1; the only substrate-specific code per §12) | Phase 09 |
|
||||
| `terraform/` | State backend + provider config (S3 state + DynamoDB lock) | Phase 08+ |
|
||||
| `modules-ir/` | IR-typed L1/L2 modules (`l1-s3`, `l2-static-asset`) | Phase 09–10 |
|
||||
| `scripts/` | v1.1 verify scripts (`verify_phaseNN.sh`) | Phase 06+ |
|
||||
| `demo/` | Archived v1.0 executive demo (tag `v1.1.0`); runs locally via `demo/scripts/run_demo.sh --no-upload` | complete |
|
||||
| `.ciagent/` | CIAgent metadata (plans, decisions, personas, roadmap, research) | active |
|
||||
| `docs/` | Upstream vision + architecture sources | active |
|
||||
|
||||
- `acdl` (this repo) — platform + stubs + reusable workflows
|
||||
- `acdl-contracts` — developer surface (`contract.yaml` + issue trigger)
|
||||
- `acdl-evidence` — audit timeline (served via raw file URLs; Gitea has no
|
||||
native Pages — see `.ciagent/ARCHITECTURE.md` Gitea API Surface table)
|
||||
## Running the archived demo
|
||||
|
||||
## Project metadata
|
||||
|
||||
See `.ciagent/PROJECT.md` for the full spec, `.ciagent/ROADMAP.md` for the
|
||||
5-phase breakdown, `.ciagent/REQUIREMENTS.md` for traceable requirements,
|
||||
and `.ciagent/PERSONAS.md` for the active persona roster.
|
||||
|
||||
## Phase 01 verification
|
||||
|
||||
After running `scripts/gitea_setup.sh` (which creates `acdl-contracts` and
|
||||
`acdl-evidence` in the org and pushes the placeholder `index.html`), run:
|
||||
The v1.0 demo is an archived artifact. To re-run it locally:
|
||||
|
||||
```bash
|
||||
ACDL_GITEA_TOKEN=<token> scripts/verify_phase01.sh
|
||||
bash demo/scripts/run_demo.sh --no-upload
|
||||
```
|
||||
|
||||
The script confirms:
|
||||
- both new repos exist via the Gitea API
|
||||
- the raw `index.html` URL on `acdl-evidence` returns HTTP 200
|
||||
- the `qa` and `prod` branches exist on `acdl-contracts`
|
||||
|
||||
Exit 0 = Phase 01 success criteria met.
|
||||
The demo deck is at [`demo/ACDL_DEMO.md`](demo/ACDL_DEMO.md). The demo runs
|
||||
entirely on local stubs — no AWS, no AI — and shows intent and safety
|
||||
behavior rather than provisioning real cloud resources. It is the reference
|
||||
of intent for the real platform; it is not the platform itself.
|
||||
@@ -0,0 +1,368 @@
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
paginate: true
|
||||
size: 16:9
|
||||
header: 'ACDL · Agentic Cloud Delivery Platform'
|
||||
footer: 'Executive Demo · v1.0'
|
||||
style: |
|
||||
/* S&P Global-inspired palette */
|
||||
:root {
|
||||
--sp-red: #C8102E;
|
||||
--sp-red-dark: #8E0B20;
|
||||
--sp-ink: #1A1A1A;
|
||||
--sp-slate: #4A4A4A;
|
||||
--sp-gray: #6E6E6E;
|
||||
--sp-line: #D6D6D6;
|
||||
--sp-bg: #FFFFFF;
|
||||
--sp-tint: #F4F4F4;
|
||||
}
|
||||
section {
|
||||
font-size: 24px;
|
||||
color: var(--sp-ink);
|
||||
background: var(--sp-bg);
|
||||
font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
|
||||
padding: 50px 60px;
|
||||
}
|
||||
section.title {
|
||||
text-align: center;
|
||||
background: var(--sp-red);
|
||||
color: #FFFFFF;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: center;
|
||||
}
|
||||
section.title h1 {
|
||||
color: #FFFFFF;
|
||||
font-size: 64px;
|
||||
margin-bottom: 0;
|
||||
border: none;
|
||||
}
|
||||
section.title h2 {
|
||||
color: #FFFFFF;
|
||||
border: none;
|
||||
font-weight: 400;
|
||||
}
|
||||
section.title strong { color: #FFFFFF; }
|
||||
h1 {
|
||||
color: var(--sp-red);
|
||||
font-size: 40px;
|
||||
font-weight: 700;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
h2 {
|
||||
color: var(--sp-red);
|
||||
border-bottom: 3px solid var(--sp-red);
|
||||
padding-bottom: 6px;
|
||||
font-weight: 700;
|
||||
}
|
||||
h3 {
|
||||
color: var(--sp-red-dark);
|
||||
font-weight: 600;
|
||||
margin-top: 24px;
|
||||
}
|
||||
ul, ol { color: var(--sp-slate); }
|
||||
li { margin-bottom: 6px; }
|
||||
strong { color: var(--sp-ink); }
|
||||
table {
|
||||
font-size: 18px;
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 12px 0;
|
||||
}
|
||||
th {
|
||||
background: var(--sp-red);
|
||||
color: #FFFFFF;
|
||||
text-align: left;
|
||||
padding: 10px 12px;
|
||||
font-weight: 600;
|
||||
border: 1px solid var(--sp-red-dark);
|
||||
}
|
||||
td {
|
||||
padding: 8px 12px;
|
||||
border: 1px solid var(--sp-line);
|
||||
color: var(--sp-slate);
|
||||
}
|
||||
tr:nth-child(even) td { background: var(--sp-tint); }
|
||||
pre {
|
||||
font-size: 13px;
|
||||
background: var(--sp-tint);
|
||||
border-left: 4px solid var(--sp-red);
|
||||
padding: 14px 16px;
|
||||
border-radius: 0;
|
||||
color: var(--sp-ink);
|
||||
}
|
||||
code {
|
||||
background: var(--sp-tint);
|
||||
color: var(--sp-red-dark);
|
||||
padding: 1px 5px;
|
||||
border-radius: 2px;
|
||||
font-family: 'Menlo', 'Consolas', monospace;
|
||||
}
|
||||
pre code {
|
||||
background: none;
|
||||
color: var(--sp-ink);
|
||||
padding: 0;
|
||||
}
|
||||
blockquote {
|
||||
border-left: 5px solid var(--sp-red);
|
||||
background: var(--sp-tint);
|
||||
padding: 10px 16px;
|
||||
color: var(--sp-slate);
|
||||
font-style: italic;
|
||||
border-radius: 0;
|
||||
}
|
||||
header {
|
||||
color: var(--sp-red);
|
||||
font-weight: 700;
|
||||
font-size: 14px;
|
||||
}
|
||||
footer {
|
||||
color: var(--sp-gray);
|
||||
font-size: 12px;
|
||||
}
|
||||
section::after {
|
||||
color: var(--sp-red);
|
||||
font-weight: 700;
|
||||
}
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
|
||||
# ACDL
|
||||
## Agentic Cloud Delivery Platform
|
||||
|
||||
Automatic. Safe. Audited. — in 30 minutes, on stubs.
|
||||
|
||||
v1.0 · GitHub Actions · stub-driven
|
||||
|
||||
<!--
|
||||
30-min exec demo. Emphasize: we prove INTENT and SAFETY, not provision real infra.
|
||||
Everything runs as local stubs on Linux via GitHub Actions. No AWS.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# The Problem
|
||||
|
||||
### Today, deploying infrastructure takes **weeks**
|
||||
|
||||
- Ticket → triage queue → copy-paste config → peer review → security review → waiting for central IT to release
|
||||
|
||||
> Two weeks of human latency for a service that should take minutes.
|
||||
|
||||
### What we want instead
|
||||
|
||||
- Developer commits a **contract** → pipeline runs
|
||||
- Safety **computed** automatically (confidence signal)
|
||||
- Manual gates only where they matter (QA, Prod)
|
||||
- Every step written to a tamper-evident **evidence stream**
|
||||
|
||||
<!--
|
||||
Set the pain. Ask: who has lived this? Then pivot to the vision.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# How It Works
|
||||
|
||||
```
|
||||
┌────────────── acdl-contracts ──────────────┐
|
||||
Developer ──▶│ commit contract.yaml │
|
||||
└───────┬───────────────────────────────────┘
|
||||
│ (push)
|
||||
Citizen ┌─────────┴──────────┐
|
||||
│ "ingest gas pricing into data lake"
|
||||
▼
|
||||
Claude agent ──▶ contract.yaml ─┘
|
||||
│ (push)
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ reusable │
|
||||
│ GitHub Actions │
|
||||
│ pipeline │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
Dev (auto) QA (approval) Prod (approval)
|
||||
│
|
||||
▼
|
||||
evidence_writer ─▶ audit.json (hash-chained) ─▶ Pages timeline
|
||||
```
|
||||
|
||||
Two entry paths, **one** pipeline, **one** audit trail — developer via GitHub, citizen developer via their own Claude agent.
|
||||
|
||||
<!--
|
||||
Two surfaces: developers push contracts directly to GitHub; citizen developers prompt a Claude agent they own, which writes and pushes the contract for them.
|
||||
Both converge on one GitHub Actions pipeline with three stages.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# The Safety Story
|
||||
|
||||
### Computed, not requested
|
||||
|
||||
| Signal | Behavior |
|
||||
|--------|----------|
|
||||
| **Base confidence** | 0.90 |
|
||||
| **On policy violation** | drop to 0.40 + reason code |
|
||||
| **Gate threshold** | ≥ 0.50 to proceed past Dev |
|
||||
|
||||
### Policy (v1)
|
||||
- `public-ingress: true` → `POLICY_VIOLATION:PUBLIC_INGRESS`
|
||||
|
||||
### Evidence
|
||||
- Each event appended to `audit.json` with SHA-256 link to previous (`prev_hash` + `hash`)
|
||||
- Published to Pages → vanilla-JS timeline
|
||||
|
||||
<!--
|
||||
Safety is computed by the platform, not asked of the developer.
|
||||
Threshold 0.50 is exact → 0.90 passes, 0.40 halts. That's what makes the three scenarios deterministic.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 1 — Developer Self-Service
|
||||
|
||||
### Trigger
|
||||
Developer commits a valid `contract.yaml` requesting **`l2-commodity-price-feed`** via **GitHub**.
|
||||
|
||||
### What you'll see
|
||||
- **Dev:** policy ✅ → apply api-gateway, lambda, s3 → confidence **0.90** → proceed
|
||||
- **QA:** pipeline pauses → click **Approve**
|
||||
- **Prod:** pipeline pauses → click **Approve**
|
||||
- **Finalize:** `audit.json` committed → Pages timeline updates
|
||||
|
||||
### Evidence outcome
|
||||
Timeline shows: contract received → policy pass → apply × 3 → confidence 0.90 → QA → Prod → published.
|
||||
|
||||
<!--
|
||||
Normal developer flow: human writes the contract, pushes to GitHub, the GitHub Action pipeline runs.
|
||||
Narrate: developer commits and walks away; platform does the rest.
|
||||
Pause visibly at each gate so the audience sees human-in-the-loop.
|
||||
End by refreshing the Pages timeline.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 1 — Journey
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
classDef gh fill:#F4F4F4,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef stage fill:#C8102E,stroke:#8E0B20,stroke-width:1px,color:#FFFFFF
|
||||
classDef gate fill:#FFFFFF,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef evidence fill:#F4F4F4,stroke:#C8102E,stroke-width:1px,color:#1A1A1A
|
||||
|
||||
D["Developer"]:::gh -->|"writes contract.yaml"| GH["GitHub<br/>acdl-contracts"]:::gh
|
||||
GH -->|"push triggers<br/>GitHub Action"| DEV["Dev<br/>(autonomous)"]:::stage
|
||||
DEV -->|"policy ✅ · confidence 0.90"| QA["QA<br/>approval gate"]:::gate
|
||||
QA -->|"approve"| PROD["Prod<br/>approval gate"]:::gate
|
||||
PROD -->|"approve"| FIN["Finalize<br/>commit audit.json"]:::stage
|
||||
FIN --> TL["GitHub Pages<br/>timeline"]:::evidence
|
||||
```
|
||||
|
||||
<!--
|
||||
Point to the two approval gates — QA and Prod — both human clicks.
|
||||
The whole chain from commit to timeline is one GitHub Actions workflow.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 2 — Citizen Developer
|
||||
|
||||
### Trigger
|
||||
Non-technical user prompts their **own Claude agent** in natural language:
|
||||
|
||||
> "I need a new service to ingest real-time natural gas pricing data into our data lake."
|
||||
|
||||
### What you'll see
|
||||
- Claude agent parses intent, writes `contract.yaml` for **`l2-commodity-price-feed`**, pushes a branch
|
||||
- Issue **closed**; branch push triggers the **identical** pipeline from Scenario 1
|
||||
- Citizen developer follows the run all the way to **Prod**
|
||||
|
||||
### Evidence outcome
|
||||
Timeline is **indistinguishable** from Scenario 1 — the agentic surface is first-class, not a bolt-on.
|
||||
|
||||
<!--
|
||||
Punchline: same timeline, same safety, same audit — different entry.
|
||||
The citizen developer owns and drives their own Claude agent; they are the actor, not the platform.
|
||||
Normal developers (Scenario 1) keep using GitHub directly — two surfaces, one pipeline, one audit.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 2 — Journey
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
classDef cit fill:#F4F4F4,stroke:#C8102E,stroke-width:2px,color:#1A1A1A
|
||||
classDef agent fill:#C8102E,stroke:#8E0B20,stroke-width:1px,color:#FFFFFF
|
||||
classDef stage fill:#1A1A1A,stroke:#1A1A1A,stroke-width:1px,color:#FFFFFF
|
||||
classDef gate fill:#FFFFFF,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef evidence fill:#F4F4F4,stroke:#C8102E,stroke-width:1px,color:#1A1A1A
|
||||
|
||||
CD["Citizen developer"]:::cit -->|"natural-language<br/>prompt"| CL["Claude agent<br/>(citizen-owned)"]:::agent
|
||||
CL -->|"generates<br/>contract.yaml"| GH["GitHub<br/>acdl-contracts"]:::cit
|
||||
GH -->|"push triggers<br/>GitHub Action"| DEV["Dev<br/>(autonomous)"]:::stage
|
||||
DEV -->|"policy ✅ · confidence 0.90"| QA["QA<br/>approval gate"]:::gate
|
||||
QA -->|"approve"| PROD["Prod<br/>approval gate"]:::gate
|
||||
PROD -->|"approve"| FIN["Finalize<br/>commit audit.json"]:::stage
|
||||
FIN --> TL["GitHub Pages<br/>timeline"]:::evidence
|
||||
```
|
||||
|
||||
<!--
|
||||
Highlight the red Claude-agent node — owned by the citizen, not by the platform.
|
||||
From GitHub onward the journey is identical to Scenario 1.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 3 — The Safety Net
|
||||
|
||||
### Trigger
|
||||
Developer commits a **malicious** `contract.yaml` for `l2-regulatory-reporting` via **GitHub**:
|
||||
|
||||
```yaml
|
||||
stack: l2-regulatory-reporting
|
||||
public-ingress: true
|
||||
```
|
||||
|
||||
### What you'll see
|
||||
- **Dev:** `policy_checker` → `POLICY_VIOLATION:PUBLIC_INGRESS`
|
||||
- `confidence_signal` drops 0.90 → **0.40**
|
||||
- `0.40 < 0.50` → pipeline **halts in Dev**
|
||||
- Rejection reason written to the evidence stream
|
||||
|
||||
### Evidence outcome
|
||||
Timeline shows the attempted deploy, the violation, the confidence drop, and the **halt** — visible and explained.
|
||||
|
||||
<!--
|
||||
The safety money shot. The platform said NO, and said WHY, on the record.
|
||||
No human had to catch it — the confidence signal computed the risk.
|
||||
Contrast with The Problem's old-world review queue.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 3 — Journey
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
classDef gh fill:#F4F4F4,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef stage fill:#C8102E,stroke:#8E0B20,stroke-width:1px,color:#FFFFFF
|
||||
classDef halt fill:#1A1A1A,stroke:#1A1A1A,stroke-width:1px,color:#FFFFFF
|
||||
classDef evidence fill:#F4F4F4,stroke:#C8102E,stroke-width:1px,color:#1A1A1A
|
||||
|
||||
D["Developer"]:::gh -->|"writes malicious<br/>contract.yaml"| GH["GitHub<br/>acdl-contracts"]:::gh
|
||||
GH -->|"push triggers<br/>GitHub Action"| DEV["Dev<br/>(autonomous)"]:::stage
|
||||
DEV -->|"POLICY_VIOLATION:PUBLIC_INGRESS<br/>confidence 0.90 → 0.40"| HALT["Halt in Dev<br/>+ rejection reason"]:::halt
|
||||
HALT --> TL["GitHub Pages<br/>timeline"]:::evidence
|
||||
```
|
||||
|
||||
<!--
|
||||
The black halt node is the whole point — pipeline stops, evidence records why.
|
||||
Notice there are no QA/Prod gates on this path; the journey ends at Dev.
|
||||
-->
|
||||
@@ -0,0 +1,55 @@
|
||||
# Elaborate developer contract — energy trading price feed.
|
||||
#
|
||||
# Schema (D-021): stack + inputs (open-ended string map) + public-ingress.
|
||||
# The `stack` field MUST match an L2 folder name under modules/l2/.
|
||||
# The `inputs` map is free-form string values; these are L2-level params
|
||||
# that travel with the deployment into state.json and the audit trail.
|
||||
# The L1 input values are declared by the L2's manifest.yaml, not here.
|
||||
#
|
||||
# Commit this to acdl-contracts as contract.yaml to trigger the pipeline:
|
||||
# git add contract.yaml && git commit -m "feat: deploy price feed (prod)" && git push
|
||||
|
||||
stack: l2-commodity-price-feed
|
||||
|
||||
inputs:
|
||||
# --- Environment + ownership ---
|
||||
environment: prod
|
||||
owner: commodity-trading-platform-team
|
||||
team: power-and-gas-desk
|
||||
cost_center: CC-TRD-4471
|
||||
change_ticket: CHG-2026-07-21-093
|
||||
|
||||
# --- Business context (rides into the audit timeline) ---
|
||||
business_owner: kchen@jccapital.xyz
|
||||
oncall_email: sre-commodity@example.com
|
||||
sla_tier: T1
|
||||
business_hours: "Mon-Fri 07:00-19:00 ET"
|
||||
data_classification: internal
|
||||
|
||||
# --- Source feed contract (business-facing) ---
|
||||
feed_vendor: Platts
|
||||
feed_name: natural-gas-daily-settlement
|
||||
feed_cadence: daily
|
||||
feed_timezone: US/Eastern
|
||||
symbols: "NG-WTI-HH,NG-HH-M,NG-PJM"
|
||||
retry_policy: backoff-3x-15min
|
||||
dead_letter_queue: commodity-price-dlq
|
||||
|
||||
# --- Deployment knobs (consumed by the pipeline; passed to L1s via L2 manifest) ---
|
||||
replicas: "3"
|
||||
cpu_request: "500m"
|
||||
memory_request: "1Gi"
|
||||
autoscale_min: "2"
|
||||
autoscale_max: "8"
|
||||
log_retention_days: "90"
|
||||
archive_retention_days: "2555"
|
||||
|
||||
# --- Operational flags ---
|
||||
enable_canary: "true"
|
||||
canary_percentage: "10"
|
||||
enable_pagerduty: "true"
|
||||
enable_cost_alerts: "true"
|
||||
cost_alert_threshold_usd: "500"
|
||||
|
||||
# Policy-gated field. true -> POLICY_VIOLATION:PUBLIC_INGRESS -> confidence 0.40 < 0.50 -> Dev rejects (Act 4).
|
||||
public-ingress: false
|
||||
@@ -0,0 +1,55 @@
|
||||
# Elaborate developer contract — regulatory reporting (with policy violation).
|
||||
#
|
||||
# Same schema as the price-feed example, but with public-ingress: true,
|
||||
# which triggers Act 4: the policy_checker fails, the confidence_signal
|
||||
# drops to 0.40, the 0.50 gate halts the pipeline in Dev, and the
|
||||
# rejection appears on the evidence timeline.
|
||||
#
|
||||
# Commit this to acdl-contracts as contract.yaml to reproduce Act 4:
|
||||
# git add contract.yaml && git commit -m "feat: deploy regulatory reporting" && git push
|
||||
|
||||
stack: l2-regulatory-reporting
|
||||
|
||||
inputs:
|
||||
# --- Environment + ownership ---
|
||||
environment: prod
|
||||
owner: compliance-and-controls-team
|
||||
team: regulatory-reporting-desk
|
||||
cost_center: CC-CMP-9902
|
||||
change_ticket: CHG-2026-07-21-118
|
||||
business_owner: compliance@jccapital.xyz
|
||||
oncall_email: sre-regulatory@example.com
|
||||
sla_tier: T0
|
||||
business_hours: "24x7"
|
||||
data_classification: confidential
|
||||
|
||||
# --- Regulatory context ---
|
||||
regulator: FERC
|
||||
filing_frequency: monthly
|
||||
filing_deadline_day_of_month: "15"
|
||||
reporting_period: 2026-Q3
|
||||
jurisdiction: US-Federal
|
||||
legal_hold: "false"
|
||||
|
||||
# --- Deployment knobs ---
|
||||
replicas: "2"
|
||||
cpu_request: "1000m"
|
||||
memory_request: "2Gi"
|
||||
autoscale_min: "2"
|
||||
autoscale_max: "4"
|
||||
log_retention_days: "365"
|
||||
archive_retention_days: "2555"
|
||||
enable_encryption_at_rest: "true"
|
||||
enable_kms_rotation: "true"
|
||||
|
||||
# --- Operational flags ---
|
||||
enable_canary: "false"
|
||||
enable_pagerduty: "true"
|
||||
enable_cost_alerts: "true"
|
||||
cost_alert_threshold_usd: "1000"
|
||||
|
||||
# POLICY VIOLATION — this is the Act 4 trigger.
|
||||
# The policy_checker.py will emit: POLICY_VIOLATION:PUBLIC_INGRESS
|
||||
# The confidence_signal.py will return: {"score": 0.40, "reason": "POLICY_VIOLATION:PUBLIC_INGRESS"}
|
||||
# The 0.50 gate halts the pipeline in Dev; mock_executor never runs.
|
||||
public-ingress: true
|
||||
@@ -0,0 +1,452 @@
|
||||
# Architecture Document v0.2 + Executive Demo Plan
|
||||
|
||||
Three things to set up before I deliver the document, because they determine how I write the doc:
|
||||
|
||||
1. What is locked from the resolution session. Eight items: environment model (Path A — dev-only autonomous, no staging), substrate abstraction (Target Stack IR + adapter pattern, Terraform adapter in v1), policy toolchain (Checkov for Terraform plan, Kyverno for K8s, OPA last resort), separation of duties (CODEOWNERS for routing + DynamoDB outbox for identity distinctness), policy normalization PolicyCheckResult schema with engine adapters), HITL matrix (full 8-concern matrix with evidence, freshness, source), HITL timeout (1d warn, 2d freeze), HITL rollback (pre-execution model, audit chain extended, no partial deploy).
|
||||
|
||||
2. What is still open after the session. Eleven items, listed in the updated Section 13. They are the gating items for v1.0.
|
||||
|
||||
3. Doc-sync item. The CDLC reference document (not in scope of this architecture) describes staging as an environment and uses targetEnvironments: [staging, production] in its contract example. Path A invalidates that. The CDLC document is the responsibility of its own owners, but this architecture flags the inconsistency so the CDLC revision can be scheduled in the same change set.
|
||||
|
||||
The architecture document is below, followed by the executive demo plan, followed by the final three questions I need resolved before v1.0.
|
||||
|
||||
---
|
||||
|
||||
# Agentic Cloud Delivery Platform — Architecture Document
|
||||
|
||||
Status: Draft v0.2. Section 13 lists 11 open decisions. Eight of the original 15 open items are now locked; seven remain from Section 13 plus four new sub-decisions surfaced during resolution.
|
||||
|
||||
Companion to: Agentic Cloud Delivery Vision [1].
|
||||
|
||||
Authoring principle: The vision is the source of truth for why [1]; this document is the source of truth for how. Where the two conflict, the vision wins.
|
||||
|
||||
Resolution session log (this revision):
|
||||
|
||||
| ID | Question | Resolution |
|
||||
|---|---|---|
|
||||
| Q1 | Environment model | Path A locked. Dev is the only autonomous environment. QA HITL at qa. SRE HITL at prod and dr. Staging does not exist. |
|
||||
| Q1.2 | Substrate trajectory | Substrate abstraction locked. L1/L2 are defined against a Target Stack IR. Substrate adapters compile the IR to a substrate execution plan. v1 ships only the Terraform adapter. |
|
||||
| Q1.3 | OpenTofu timing | 🟡 OPEN (W3.D-adjacent). No specific version or trigger committed. |
|
||||
| Q2.1 | Policy toolchain | Locked. Checkov for Terraform plan policy. Kyverno for K8s-native and platform-internal policy. OPA/Rego reserved for cross-resource cases; explicitly last resort due to Rego complexity. |
|
||||
| Q2.2 | Separation of duties | Locked. GitHub CODEOWNERS routes the right reviewer to the right environment. Platform-internal identity record in DynamoDB outbox enforces qaApprover ≠ prodApprover for the same contract. |
|
||||
| Q2.3 | Policy normalization | Locked. PolicyCheckResult JSON schema is the contract between engines and the confidence signal. Engine-specific adapters translate native output to the schema. |
|
||||
| Q3 | HITL matrix + timeout + rollback | Locked (full 8-concern matrix in §10). Pre-execution gate model. 1 business day = warn + escalate. 2 business days = auto-freeze + re-submit. Rejection extends the audit chain, no partial deploy to roll back. |
|
||||
| W1.A | AI-refinement trigger | 🟡 OPEN. Recommendation pending sign-off. |
|
||||
| W1.B | Multi-stack edge case rule | 🟡 OPEN. Recommendation pending sign-off. |
|
||||
| W2.A | Tag mutability for prod | 🟡 OPEN. Recommendation pending sign-off. |
|
||||
| W3.D | L1/L2 standard versioning details | 🟡 OPEN. |
|
||||
| W3.E | Schema mandatory vs. optional inputs | 🟡 OPEN. |
|
||||
| BA.A–F | Beyond-architecture questions | 🟡 OPEN (6 items). |
|
||||
|
||||
---
|
||||
|
||||
## 0. Purpose
|
||||
|
||||
This document encodes the architectural commitments that realize the vision [1]. The resolution session has closed eight open items; the document is now at v0.2 with eleven open items remaining, listed in Section 13. Every locked commitment is grounded in either a vision tenet or a specific decision made during resolution.
|
||||
|
||||
The structure remains: four layers (L1 primitives, L2 composed stacks, L3A developer surface, L3B agentic surface) plus five cross-cutting concerns (central pipeline, contract schema, confidence signal, audit stream, HITL mechanics), with one addition: the substrate abstraction layer (Section 12) is now a first-class architectural concern, not an implementation detail.
|
||||
|
||||
## 1. Architectural Overview
|
||||
|
||||
The platform remains four layers and five cross-cutting concerns. The substrate abstraction is added as a sixth cross-cutting concern in Section 12 because it is the binding constraint for the L1/L2 model, the central pipeline, and the policy toolchain.
|
||||
|
||||
The vision's "Two Consumer Surfaces, One Platform" tenet [1] remains the constraint that binds all concerns: L3A and L3B converge on the same contract schema, the same policy envelope, and the same evidence stream.
|
||||
|
||||
Locked additions this revision:
|
||||
|
||||
- The environment model is dev (autonomous) → qa (QA HITL) → prod (SRE HITL) → dr (SRE HITL). Staging does not exist.
|
||||
|
||||
- L1/L2 are substrate-agnostic in shape; substrate adapters are the only substrate-specific component.
|
||||
|
||||
## 2. Layer 1 — Foundational Primitives
|
||||
|
||||
Purpose. Single-purpose, substrate-agnostic primitive modules representing the smallest reusable infrastructure pieces. L1 modules do not compose with other L1 modules; L1 takes its environment as input.
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- No inter-L1 references. L1 may call Terraform data sources.
|
||||
|
||||
- Semver with three triggers (interface → MAJOR, behavior → MINOR, lifecycle → PATCH).
|
||||
|
||||
- Immutability on publication.
|
||||
|
||||
- 12-month deprecation window.
|
||||
|
||||
- AI refinement is a flag.
|
||||
|
||||
🟡 OPEN (W1.A): AI-refinement operational trigger. The criterion for flipping aiRefinement from false to true needs a falsifiable operational signal. Recommendation: joint condition — N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in the last 6 months AND Infra & Ops holds a unilateral override. Pending sign-off.
|
||||
|
||||
🟡 OPEN (sub-decision surfaced this revision): The L1 module's interface field is defined against the Target Stack IR, not against Terraform's variable block directly. In v1, the IR is shaped to round-trip cleanly to Terraform, but the schema is substrate-agnostic. Pending v1 implementation details in Section 12.
|
||||
|
||||
## 3. Layer 2 — Composed Stacks
|
||||
|
||||
Purpose. Combine L1 primitives into deployable infrastructure shapes. Each codebase maps to one canonical L2 stack; the stack is either a parameterized module (Shape X) or a thin-composition layer (Shape Y).
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- 1 codebase = 1 L2 stack (default), with multiStack: true for exceptions.
|
||||
|
||||
- Shape X or Shape Y.
|
||||
|
||||
- Hierarchical composition, max depth 5, only registered L1s.
|
||||
|
||||
- Pipeline quality checks: secrets-in-plaintext, public ingress, IAM wildcard, KMS key reference, tag compliance, naming convention.
|
||||
|
||||
- Restricted from thin-composition: IAM principal creation, network boundary creation, key/secret creation, external data transfer.
|
||||
|
||||
- Auto-promote after 3 observed usages.
|
||||
|
||||
🟡 OPEN (W1.B): Multi-stack edge case rule. The multiStack: true exception needs a falsifiable rule. Recommendation: permitted only for (a) DR-region mirror of the primary stack, (b) time-boxed experimental stack with TTL ≤ 30 days, (c) explicit Infra & Ops approval for a documented reason captured in multiStack.justification. Pending sign-off.
|
||||
|
||||
🟡 OPEN (sub-decision surfaced this revision): The L2 thin-composition tree's wires field is defined against the IR's relationship type, not against a Terraform module block. The IR → Terraform translation is the Terraform adapter's job (Section 12). The thin-composition pipeline itself is substrate-agnostic.
|
||||
|
||||
## 4. Layer 3A — Developer Consumer Surface
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- Tag-based reference to the central pipeline template.
|
||||
|
||||
- Developer-owned workflow file, no platform auto-sync.
|
||||
|
||||
- L3A and L3B are parallel paths, not a progression.
|
||||
|
||||
🟡 OPEN (W2.A): Tag mutability for production-bound references. Path A (tag throughout with protection) vs. Path B (tag for dev/qa, SHA for prod). Recommendation: Path B, justified by the vision's "Audit truth lives outside the repository" bet [1] and the "Not a mutable audit log" anti-goal [1]; SHA-pinning is the only guarantee that the exact bytes reviewed in dev/qa are the bytes deployed to prod. The platform provides a CLI command that resolves the current tag to its SHA for prod-bound workflows. Pending sign-off.
|
||||
|
||||
## 5. Layer 3B — Agentic Consumer Surface
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- Hybrid runtime, skill as markdown, agent as executor.
|
||||
|
||||
- Trust model: trust and always verify on the platform side.
|
||||
|
||||
- Skill envelope (4 dimensions).
|
||||
|
||||
- Stateless agents, all state in the platform.
|
||||
|
||||
Environment progression — locked (this revision):
|
||||
|
||||
| Environment | Autonomy | Attester | Gate |
|
||||
|---|---|---|---|
|
||||
| dev | Full autonomy (no HITL) | — | Confidence signal ≥ 0.50, all six inputs present |
|
||||
| qa | Held for attestation | QA | GitHub Deployment approval + full QA matrix (see §10) |
|
||||
| prod | Held for attestation | SRE | GitHub Deployment approval + full SRE matrix (see §10) |
|
||||
| dr | Held for attestation | SRE | GitHub Deployment approval + dr-drill evidence (see §10) |
|
||||
|
||||
Staging is removed. Dev is the only autonomous environment and absorbs integration, contract, security smoke, and performance smoke validation. The CDLC reference document's environment model is a doc-sync item flagged at the top of this document.
|
||||
|
||||
Profile marker: profile: agentic unlocks L3B-specific fields naturalLanguageIntent, confidenceAtSubmission, agentTrace).
|
||||
|
||||
🟡 OPEN (BA.A): Skill catalog. Which skills exist in the initial L3B capability set, who decides what gets added, how are skills deprecated. Pending resolution.
|
||||
|
||||
## 6. Cross-Cutting — Central Pipeline Template
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- JSON Schema (draft 2020-12) with thin domain-specific wrapper.
|
||||
|
||||
- Central repo + generated client libraries.
|
||||
|
||||
- Multi-stage validation pipeline (schema → policy → NFR → confidence).
|
||||
|
||||
- Distributed enrichment.
|
||||
|
||||
- GitOps reconciler + Terraform execution layer.
|
||||
|
||||
Locked additions this revision:
|
||||
|
||||
- The GitOps reconciler is the platform's K8s API. The cdlc-gitops repository's state materializes into K8s CRDs (ArgoCD Applications or Flux Kustomizations) that the reconciler watches. This is the platform's internal state surface.
|
||||
|
||||
- The pipeline emits a PolicyCheckResult record per policy rule evaluated. The confidence signal consumes these as one normalized input (Section 8).
|
||||
|
||||
🟡 OPEN (W3.D): L1/L2 standard versioning details — semver scheme, pin model, evolution compatibility contract.
|
||||
|
||||
🟡 OPEN (W3.E): Schema mandatory vs. optional inputs — which are required for all consumers, which are required only for higher environments, which are always optional.
|
||||
|
||||
## 7. Cross-Cutting — Contract Schema
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- Central repo + generated client libraries.
|
||||
|
||||
- Strict fail-fast at schema stage, multi-stage validation pipeline with reason codes from a published vocabulary.
|
||||
|
||||
🟡 OPEN (W3.E): Schema mandatory vs. optional inputs. The CDLC reference contract example [1] is illustrative; the v1 contract schema needs explicit per-field mandatory/optional declarations per environment.
|
||||
|
||||
## 8. Cross-Cutting — Confidence Signal
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- Six canonical inputs.
|
||||
|
||||
- Weighted sum with per-input breakdown.
|
||||
|
||||
- Per-environment thresholds: dev ≥ 0.50, qa ≥ 0.75, prod ≥ 0.90, dr ≥ 0.95.
|
||||
|
||||
- Structured output { score, band, perInput, reasonCodes }.
|
||||
|
||||
- 1-year storage, no algorithm retraining in v1.
|
||||
|
||||
- Halt with explicit reason on missing input.
|
||||
|
||||
Locked additions this revision:
|
||||
|
||||
- The policy check results input is a list of PolicyCheckResult records from the normalized schema (Section 9, 12). The signal does not know which engine produced which result.
|
||||
|
||||
- Severity → score penalty mapping: critical → hard override to mandatory block, high → -0.2, medium → -0.05, low → -0.01, info → 0.0. One critical finding hard-overrides the score regardless of all other inputs.
|
||||
|
||||
🟡 OPEN (BA.B): Threshold tuning policy. The initial thresholds (dev 0.50, qa 0.75, prod 0.90, dr 0.95) are starting values. The tuning process, false-positive/false-negative tracking, and override authority are pending.
|
||||
|
||||
## 9. Cross-Cutting — Audit and Evidence Stream
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- Tiered audit ledger: S3 with Object Lock in compliance mode (cold, source of truth, 7-year retention) + GitHub audit repo (hot, query index, not part of the chain).
|
||||
|
||||
- Daily checkpoints.
|
||||
|
||||
- Event schema: JWS detached signature, prev_event_hash chain, controlled-vocabulary event_type.
|
||||
|
||||
- Outbox pattern with local durable outbox + async worker.
|
||||
|
||||
- Linkage via workflow run ID or agent invocation ID.
|
||||
|
||||
Locked additions this revision:
|
||||
|
||||
- The outbox database is DynamoDB. RPO is zero (synchronous write to local outbox before contract submission ack); RTO is the async worker's recovery from the dead-letter queue. Single-region in v1; multi-region is a v2 concern.
|
||||
|
||||
- The outbox also stores the per-contract QA and prod approver identities (Section 10). The platform-internal identity-distinctness check reads from this outbox. This is the only durable record of the approver identities outside GitHub's audit log.
|
||||
|
||||
🟡 OPEN (BA.C): On-call and operational ownership. The platform's on-call rotation, escalation paths when L3A or L3B halts unexpectedly, and the relationship to consumer on-call.
|
||||
|
||||
## 10. Cross-Cutting — Human-in-the-Loop Mechanics
|
||||
|
||||
Purpose. The human gates at higher environments. The vision's "Lower Environments are Autonomous; Higher Environments are Attested" tenet [1] and the "deliberate human attestation — not as a rubber stamp" requirement [1] are the binding constraints.
|
||||
|
||||
### 10.1 Gate model
|
||||
|
||||
Pre-execution gates. The contract is held in a "validated but not applied" state until the human attests. qa, prod, and dr are PR-based attestation gates backed by GitHub Environments with required reviewers.
|
||||
|
||||
For qa and prod, there is no partial deployment to roll back on rejection. For dr, the same model — promotion to the DR environment is a separate GitHub Deployment, gated by SRE, against a separate cluster/region. The canary/deployment-rollback model is explicitly not in scope for v1.
|
||||
|
||||
### 10.2 Reviewer routing
|
||||
|
||||
GitHub CODEOWNERS + GitHub Environment required reviewers. qa → QA team; prod → SRE team; dr → SRE team. CODEOWNERS is the routing layer; it does not enforce identity distinctness.
|
||||
|
||||
### 10.3 Separation of duties — identity distinctness
|
||||
|
||||
Mechanism is platform-internal, not GitHub-native, not Kyverno (in v1).
|
||||
|
||||
Sequence:
|
||||
|
||||
1. On promotion dev → qa, the platform reads the QA approver's GitHub identity from the GitHub Deployment approval event and writes it to the DynamoDB outbox keyed by contractId.
|
||||
|
||||
2. On promotion qa → prod, the platform reads the stored QA approver identity from the outbox and the new SRE approver identity from the GitHub Deployment approval event.
|
||||
|
||||
3. If qaApprover == prodApprover, the platform blocks the prod promotion, writes a SEPARATION_OF_DUTIES_VIOLATION event to the evidence stream, and routes a halt artifact to the SRE on-call.
|
||||
|
||||
4. The check is implemented in the central pipeline repo, not as an external policy. The platform is the only writer to the outbox; the check is in the same process that has authority to block the promotion.
|
||||
|
||||
### 10.4 Full HITL attestation matrix
|
||||
|
||||
| Env | Concern | Evidence artifact | Freshness | Source | Attester |
|
||||
|---|---|---|---|---|---|
|
||||
| qa | Functional correctness | Last successful run of contract-declared validation.e2eSuite with pass rate ≥ 99% | Last 24h | Test runner declared in contract | QA |
|
||||
| qa | Performance baseline | Load test report (k6 / Gatling / Locust) showing p99 latency < declared NFR and throughput > declared minimum | Last 7d | Load test runner declared in contract | QA |
|
||||
| qa | Security posture | Vulnerability scan (Trivy, Snyk, or contract-declared equivalent) with no criticals/highs, signed by Security on-call | Last 24h | Security scanner + Security team signature | QA |
|
||||
| qa | Contract NFRs | Platform-generated report: schema valid, NFR assertions (latency, throughput, error rate) within declared bounds | At submission | Platform contract validator | QA |
|
||||
| prod | Operational readiness | Runbook published, dashboard exists, on-call rotation assigned, alerts configured | At submission, validated against last 30d history | Platform + SRE | SRE |
|
||||
| prod | Incident response | Sev-1 runbook tabletop or live drill completed | Last 90d | SRE drill record | SRE |
|
||||
| prod | Capacity / cost | FinOps forecast for next 30d within budget envelope, cost anomaly baseline stored, budget alert configured | Forecast valid for next 30d | FinOps + SRE | SRE |
|
||||
| prod | Resilience | DR drill, chaos engineering report, backup verified | DR: 180d; chaos: 90d; backup: 30d | SRE + Platform | SRE |
|
||||
| dr | dr-region deploy with the most recent prod-bound dr drill as canary evidence | dr drill report | Last 180d | SRE | SRE |
|
||||
|
||||
### 10.5 Timeout behavior
|
||||
|
||||
| Time | State | Action |
|
||||
|---|---|---|
|
||||
| Submission | PENDING_ATTESTATION | Notify responsible team |
|
||||
| 1 business day | PENDING_ATTESTATION_WARNING | Notify team + platform on-call (elevated path); emit PENDING_ATTESTATION_TIMEOUT_WARNING event |
|
||||
| 2 business days | PENDING_ATTESTATION_AUTO_FREEZE | Auto-freeze; require re-submission; emit PENDING_ATTESTATION_AUTO_FREEZE event; new submission linked via supersedes |
|
||||
|
||||
### 10.6 Rejection and rollback
|
||||
|
||||
Rejection returns the contract to a HELD state with the rejection reason captured as a PROMOTION_REJECTED event. The consumer fixes the cause and re-submits; the new submission is linked to the rejected one via supersedes. The audit chain is extended, not torn up — matching the resolution session's answer.
|
||||
|
||||
There is no partial deployment to roll back at any v1 gate.
|
||||
|
||||
## 11. Cross-Cutting — Agentic Stack
|
||||
|
||||
Locked commitments (unchanged from v0.1):
|
||||
|
||||
- Hybrid runtime, platform-managed control plane + consumer-owned agent.
|
||||
|
||||
- Versioned, signed skill catalog over MCP.
|
||||
|
||||
- Skill envelope enforced on invocation and result submission.
|
||||
|
||||
- Consumer-owned skill execution environment. Platform does not run the skill.
|
||||
|
||||
- Stateless agents, all state in the platform.
|
||||
|
||||
Locked additions this revision:
|
||||
|
||||
- Skills are reviewed for sensitive data before release. Secrets, customer data, internal IPs, and other sensitive payloads are forbidden in skill markdown. The review is owned by Infra & Ops and is the mandatory release gate for any new skill. This is the trade-off for accepting the L3B runtime threat model (skill content is consumer-readable, so the platform must not put anything sensitive in it).
|
||||
|
||||
🟡 OPEN (BA.A): Skill catalog. Initial skill set, addition process, deprecation process.
|
||||
|
||||
## 12. Cross-Cutting — L1/L2 Substrate Execution
|
||||
|
||||
Purpose. The technical execution layer for the L1/L2 substrate, including the substrate abstraction that protects v1 from polyglot mess while leaving v2+ room to grow.
|
||||
|
||||
### 12.1 Substrate abstraction (locked this revision)
|
||||
|
||||
L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack Intermediate Representation (IR) — a substrate-neutral description of:
|
||||
|
||||
- Resources with typed input contracts, typed output contracts, and declared NFRs.
|
||||
|
||||
- Relationships (single parent per child, with a shared keyword for multi-relationship dependencies).
|
||||
|
||||
- Composition (a tree of resources with max depth 5).
|
||||
|
||||
- Policy hooks (the points in the composition where policy checks attach).
|
||||
|
||||
The L1 registry, the L2 thin-composition tree, the YML standard, and the policy check result schema are all defined against the IR. None of them is defined against any specific substrate.
|
||||
|
||||
Substrate adapters are the only substrate-specific code. An adapter compiles the IR into a substrate execution plan. v1 ships exactly one adapter: the Terraform adapter. v2+ may add additional adapters (OpenTofu, Pulumi, K8s CRDs) without architectural change.
|
||||
|
||||
v1 implementation reality: the IR is shaped to round-trip cleanly to Terraform because there is no other adapter to differentiate from. The IR and the Terraform output are nearly isomorphic in v1. As additional adapters appear in v2+, the IR gets more expressive (e.g., substrate-specific output types) and the adapters gain translation logic, but the L1 module content, the YML standard, and the thin-composition tree do not change. This is the design that prevents the polyglot mess.
|
||||
|
||||
Why not build the abstraction earlier? Building a substrate-agnostic IR before there is a second adapter to test against is speculative generality. The v1 commitment is: (1) the L1 module interface is defined against the IR even though the only adapter is Terraform, and (2) the central pipeline, registry, and policy schema consume the IR-typed contracts. The adapter is the only place where substrate terminology appears in v1.
|
||||
|
||||
### 12.2 Terraform adapter (v1)
|
||||
|
||||
The Terraform adapter:
|
||||
|
||||
- Translates the IR-typed L1 module interface to a Terraform variable block and a Terraform output block.
|
||||
|
||||
- Translates the IR-typed L2 thin-composition tree to a Terraform root module that calls the L1 modules.
|
||||
|
||||
- Translates the IR-typed relationships to Terraform module references.
|
||||
|
||||
- Emits a Terraform plan from the IR.
|
||||
|
||||
The adapter is a thin layer. It does not own L1/L2 content; it only translates.
|
||||
|
||||
### 12.3 State storage
|
||||
|
||||
Locked: S3 (state files) + DynamoDB (state locking), cloud-managed. Single-region in v1.
|
||||
|
||||
### 12.4 Policy toolchain
|
||||
|
||||
Locked:
|
||||
|
||||
- Checkov for Terraform plan policy (the four L2 thin-composition checks: secrets-in-plaintext, public ingress, IAM wildcard, KMS key reference, plus tag and naming convention). Checkov is open-source, has a broad rule catalog, and is GitOps-friendly.
|
||||
|
||||
- Kyverno for K8s-native policy (platform-internal state in the GitOps reconciler, separation-of-dues-adjacent checks if any are added in v2, future CRD validation).
|
||||
|
||||
- OPA/Rego is reserved for cross-resource policy and is explicitly last resort due to Rego complexity.
|
||||
|
||||
### 12.5 Execution layer
|
||||
|
||||
Locked: GitHub Actions. terraform plan and terraform apply run in the central pipeline repo's GitHub Actions workflow. State locking via DynamoDB. AWS credentials via OIDC federation (long-lived credentials are forbidden). The platform does not run terraform apply against a developer's workstation; all execution is in the central pipeline.
|
||||
|
||||
### 12.6 Policy result normalization (locked this revision)
|
||||
|
||||
The confidence signal does not consume raw Checkov or Kyverno output. It consumes a normalized PolicyCheckResult schema produced by substrate-specific adapters.
|
||||
|
||||
Schema (canonical form, lives in the central pipeline repo):
|
||||
|
||||
```json
|
||||
{
|
||||
"contractId": "uuid",
|
||||
"evaluatedAt": "ISO-8601",
|
||||
"engine": "checkov | kyverno | opa",
|
||||
"ruleId": "CKV_AWS_24 | KYVERNO_NO_PRIVILEGED | ...",
|
||||
"severity": "critical | high | medium | low | info",
|
||||
"result": "pass | fail | skipped | error",
|
||||
"message": "human-readable",
|
||||
"evidence": { "...engine-specific payload, opaque to the signal..." },
|
||||
"resourceRef": "IR-typed resource identifier"
|
||||
}
|
||||
```
|
||||
|
||||
The Checkov adapter runs in the same GitHub Actions step as Checkov itself and translates Checkov JSON to PolicyCheckResult records. The Kyverno adapter runs as a controller in the platform's K8s cluster and translates Kyverno PolicyReport CRDs to PolicyCheckResult records. The confidence signal's policy input component is the union of all PolicyCheckResult records, regardless of engine. The signal does not know which engine produced which result — substrate-agnostic over its inputs, matching the L1/L2 model's substrate-agnostic over its outputs.
|
||||
|
||||
### 12.7 Registry maintenance
|
||||
|
||||
Locked: L1 module publication updates the L1 registry in the same PR as the module. Registry and module land together. The registry is the IR-typed contract, not a Terraform-specific variable schema. The L1 registry, the central pipeline, and the policy schema all consume the same IR-typed contract — there is one source of truth for the L1 interface, not multiple substrate-specific copies.
|
||||
|
||||
### 12.8 Contract-schema-to-IR resolution
|
||||
|
||||
The contract schema declares the consumer's intent in IR-typed terms. The central pipeline resolves the contract to a target stack (a list of L1 module instances with their inputs and the relationships between them). The Terraform adapter compiles the target stack to a Terraform execution plan. This resolution is substrate-agnostic — the target stack is in the IR.
|
||||
|
||||
🟡 OPEN (W3.D): L1/L2 standard versioning details, including pin model and evolution compatibility contract.
|
||||
|
||||
## 13. Consolidated Open Design Decisions
|
||||
|
||||
The following 11 decisions remain open. They are the gating items for v1.0.
|
||||
|
||||
### From Wave 1 (L1/L2 Substrate)
|
||||
|
||||
- (W1.A) AI-refinement trigger. Recommendation: joint condition — N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in last 6 months AND Infra & Ops unilateral override. Pending sign-off.
|
||||
|
||||
- (W1.B) Multi-stack edge case rule. Recommendation: permitted only for (a) DR-region mirror, (b) time-boxed experimental stack with TTL ≤ 30d, (c) explicit Infra & Ops approval with documented justification in multiStack.justification. Pending sign-off.
|
||||
|
||||
### From Wave 2 (L3A/L3B)
|
||||
|
||||
- (W2.A) Tag mutability for production-bound references. Recommendation: Path B (tag for dev/qa, SHA for prod) with platform-provided CLI to resolve tag → SHA. Pending sign-off.
|
||||
|
||||
### From Wave 3 (Technical Execution)
|
||||
|
||||
- (W3.D) L1/L2 standard versioning details. Semver scheme, pin model, evolution compatibility contract.
|
||||
|
||||
- (W3.E) Schema mandatory vs. optional inputs. Per-field mandatory/optional declarations per environment.
|
||||
|
||||
### From Beyond Architecture
|
||||
|
||||
- (BA.A) Skill catalog. Initial L3B skill set, addition process, deprecation process.
|
||||
|
||||
- (BA.B) Confidence signal threshold tuning. Initial thresholds are starting values; tuning process, FP/FN tracking, override authority.
|
||||
|
||||
- (BA.C) On-call and operational ownership. Platform on-call rotation, escalation paths, relationship to consumer on-call.
|
||||
|
||||
- (BA.D) Cost and capacity governance. Cloud cost ownership, consumption reporting, runaway spend detection and halting.
|
||||
|
||||
- (BA.E) Consumer onboarding. Developer and citizen developer onboarding flow, "getting started" path through the contract schema.
|
||||
|
||||
- (BA.F) Cross-platform evolution. What changes if a second source-control system (e.g., GitLab) is added; which architectural decisions are portable.
|
||||
|
||||
## 14. Document Status and Next Steps
|
||||
|
||||
Status: v0.2. Eight of the original 15 open items are locked. Eleven remain open. The architecture is internally consistent for the locked items; resolution of the open items is the path to v1.0.
|
||||
|
||||
Doc-sync items (out of scope of this document but flagged for the same change set):
|
||||
|
||||
- The CDLC reference document's environment model assumes staging exists. Path A invalidates that. The CDLC contract example's targetEnvironments: [staging, production] must be revised to [dev, qa, prod, dr].
|
||||
|
||||
To finalize to v1.0:
|
||||
|
||||
1. Resolve the 11 open items in Section 13.
|
||||
|
||||
2. Validate the locked substrate abstraction against a real v1 implementation spike (one L1 module, one L2 thin-composition, one Terraform adapter, one contract submission end-to-end). The spike validates that the IR-shaped commitments do not require a polyglot mess.
|
||||
|
||||
3. Validate the locked HITL matrix against a tabletop exercise with QA and SRE.
|
||||
|
||||
4. Sign-off pass.
|
||||
|
||||
---
|
||||
|
||||
# Final Asks — three remaining open questions, then sign-off
|
||||
|
||||
I have three open questions that gate v1.0. Resolve them and I will revise the architecture document to v1.0 and mark it ready for implementation.
|
||||
|
||||
Q1. W1.A + W1.B — AI-refinement trigger and multi-stack edge case rule. The recommendations are in the document. Do you accept them as committed, or do you want to amend?
|
||||
|
||||
Q2. W2.A — Tag mutability for production-bound references. Path A (tag throughout with protection) vs. Path B (tag for dev/qa, SHA for prod). My recommendation is Path B with a platform CLI to resolve tag → SHA. Accept or amend?
|
||||
|
||||
Q3. BA.A — Initial L3B skill catalog. The demo plan uses 3 stub skills deploy-web-api, add-observability, add-basic-auth). For v1.0, the real platform needs a defensible initial skill set. My recommendation: start with the 5 most common infrastructure intents (web API, worker, scheduled job, static asset, basic observability bootstrap) and grow from there. The criteria for addition: a skill must (a) be reviewable for sensitive data per the locked skill-review gate, (b) be expressible as a single contract submission, and (c) have a documented use case. Accept or amend?
|
||||
|
||||
Once these three are resolved, plus the 8 remaining items (W3.D, W3.E, BA.B, BA.C, BA.D, BA.E, BA.F, and the OpenTofu timing sub-decision), the architecture moves to v1.0.
|
||||
|
||||
Sign-off request. Are you ready for me to draft v1.0 once these are resolved, or do you want to amend the v0.2 above first?
|
||||
@@ -0,0 +1,71 @@
|
||||
# Agentic Cloud Delivery Vision
|
||||
|
||||
## 1. The Friction
|
||||
|
||||
Software delivery scales with the coordination surface around it, not the engineering inside it. Most teams know how to write code; far fewer know how to author the infrastructure that runs it correctly. The result is a long tail of well-meaning services that are difficult to deploy, hard to operate, and inconsistent in their security and observability posture.
|
||||
|
||||
Once code is merged, the second friction begins. Moving a service from "merged" to "running in production with policy, observability, and security enforced" requires manual work that scales with the system, not with the change. The platform's job is to absorb both frictions — the cognitive load of getting the infrastructure right, and the operational work of getting the change to production safely.
|
||||
|
||||
## 2. The North Star
|
||||
|
||||
Consumers declare intent; the platform delivers safe production deployment through an agentic stack.
|
||||
|
||||
## 3. Core Tenets
|
||||
|
||||
* **Operations are Declared, Not Executed.** Consumers define what they need — workload shape, dependencies, non-functional requirements, policy constraints. The platform handles reconciliation, provisioning, and environment progression. The execution burden moves from the human to the platform.
|
||||
* **The Delivery Lifecycle is a Sovereign Boundary.** The platform governs the infrastructure and delivery substrate. It does not penetrate upstream product or software development lifecycles. Integration happens exclusively through validated, published contracts.
|
||||
* **Lower Environments are Autonomous; Higher Environments are Attested.** Progression through lower environments proceeds through zero-touch agentic automation. Promotion to higher-stakes environments requires deliberate human attestation — not as a rubber stamp, but as a policy-mandated act of accountability.
|
||||
* **Safety is Computed, Not Assumed.** Every delivery action produces a measurable, explainable confidence signal aggregating policy conformance, validation evidence, and historical behavior. The signal is the platform's certified answer to "is this safe to proceed?" Reliance on operator instinct or tenure is not a substitute.
|
||||
* **Infrastructure is Consumed, Not Maintained.** Compute is abstract, containerized, or serverless. The platform does not manage node, OS, or bare-metal lifecycles. Infrastructure is treated as a utility, not a craft.
|
||||
* **Two Consumer Surfaces, One Platform.** The platform serves technical developers and non-technical consumers through two coordinated interfaces. Both converge on the same contract schema, the same policy envelope, and the same evidence stream. The platform is opinionated in what it accepts, regardless of who is declaring.
|
||||
|
||||
## 4. Domain Boundaries
|
||||
|
||||
The platform begins where the artifact is compiled and ends where it runs in production under operational guardrails.
|
||||
|
||||
* **In scope:** Environment progression, cloud resource lifecycle, operational security and observability NFRs, policy enforcement, immutable audit lineage, confidence frameworks, two consumer surfaces (developer and agentic).
|
||||
* **Out of scope:** Application business logic, IDE workflows, product backlog management, sprint planning, compute requiring node-level or OS-level management.
|
||||
* **Interface:** Upstream systems interact with the platform through a strict contract boundary. The platform validates, enriches with operational standards, and reconciles the target state. Visibility into how software is authored is not required — only assurance about what is being delivered and under what policy constraints.
|
||||
|
||||
## 5. Strategic Bets
|
||||
|
||||
These are the leaps of faith underlying this vision. If any prove false, the vision requires fundamental revision.
|
||||
|
||||
* **Autonomous progression through lower environments is sufficiently safe.** End-to-end agentic progression through non-production environments — with rigorous policy, testing, and observability gates — is less risky than human-driven pipelines that rely on manual checklist discipline.
|
||||
* **Confidence can replace presumption.** A computed, policy-derived confidence signal is a legitimate arbiter for autonomous action, replacing the instinct of an operator who "knows the system."
|
||||
* **Narrow capability interfaces beat broad access.** Infrastructure capabilities are exposed to autonomous systems through constrained, domain-specific interfaces — never through raw, unbounded platform credentials. Agents call capabilities, not APIs.
|
||||
* **Audit truth lives outside the repository.** Version control is a coordination tool, not an evidentiary fortress. True compliance requires an immutable, externally-stored ledger to which the platform writes; repositories hold only lightweight attestation linkage.
|
||||
* **Pattern recognition can compound platform value over time.** As the platform observes recurring contract patterns, it can synthesize and offer reusable infrastructure compositions. This is a future capability, not a current commitment — but the platform's design must allow it.
|
||||
|
||||
## 6. Trade-offs Accepted
|
||||
|
||||
This vision is purchased with deliberate sacrifices:
|
||||
|
||||
* **Velocity over Legacy Flexibility.** Standardizing on abstract, containerized, and serverless compute eliminates undifferentiated toil. Teams operating non-cloud-native workloads must modernize or route elsewhere.
|
||||
* **Abstraction over Granular Control.** Removing node-level access sacrifices fine-tuned performance optimization in favor of uniform operability and security posture.
|
||||
* **Delegated Risk over Queue-based Safety.** An autonomous agent may occasionally halt, reject, or escalate a change that a human would have greenlit. In exchange, queue-based handoffs are eliminated from lower environments.
|
||||
* **Immutability over Convenience.** Every action leaves a cryptographic shadow in an external evidence stream. The operational overhead of signing, linking, and streaming is accepted in exchange for tamper-evident assurance rather than reliance on mutable, rewritable logs.
|
||||
|
||||
## 7. Anti-Goals
|
||||
|
||||
* **Not an upstream development platform.** No management of product backlogs, sprint ceremonies, IDE extensions, or code authorship workflows.
|
||||
* **Not a general-purpose AI.** The platform is not an open-ended conversational assistant. Autonomy is narrow, scoped to delivery and infrastructure reconciliation, and bounded by strict policy envelopes.
|
||||
* **Not a legacy infrastructure bridge.** No management of VMs, bare metal, or OS lifecycles. The substrate will not extend to non-cloud-native patterns.
|
||||
* **Not a permissive delivery highway.** No escape hatches to bypass the confidence framework or the human attestation requirements at higher environments. Speed is a byproduct of confidence and policy compliance, not an override.
|
||||
* **Not a mutable audit log.** Version control history does not satisfy regulatory evidence. Auditability requires an immutable, externally-stored stream.
|
||||
|
||||
## 8. Signals of Success
|
||||
|
||||
The vision is realized when:
|
||||
|
||||
* A merged change progresses through lower environments end-to-end without a platform engineer joining a thread, approving a ticket, or manually triggering a stage gate.
|
||||
* A developer deploys compliant, observable, and secured infrastructure by authoring a contract and a workflow — not by reading tribal runbooks or filing infrastructure requests.
|
||||
* A non-technical consumer ships a production deployment by declaring intent — without authoring a workflow, a configuration file, or a Terraform module.
|
||||
* An auditor can trace any production change to a human attestation and an immutable evidence stream without interpreting shell scripts, pipeline logs, or repository history.
|
||||
* Security, resiliency, and observability standards are satisfied automatically through platform-enriched contracts, rather than through post-hoc remediation.
|
||||
* When the platform halts a delivery, it provides a measured, explainable reason — a policy violation, an insufficient confidence signal, or a missing attestation — rather than requiring an opaque, manual-debugging exercise.
|
||||
|
||||
## What this vision is, and what it isn't
|
||||
|
||||
* **It is:** A principles document. The North Star, the tenets, the strategic bets, the anti-goals. It's intended to be the page that orients a new team, a new stakeholder, or a new architectural decision. It should not need to be rewritten when a tool changes.
|
||||
* **It isn't:** An architecture. The four-layer model (L1 Terraform primitives, L2 composed stacks, L3A developer surface, L3B agentic surface), the central pipeline template model, the schema location, the dual HITL mechanics, the enterprise evidence stream integration — all of that belongs in the architecture document, where it can be specific and evolve independently.
|
||||
Executable
+44
@@ -0,0 +1,44 @@
|
||||
#!/usr/bin/env bash
|
||||
# scripts/verify_phase06.sh - Phase 06 archive regression + layout check.
|
||||
# Lives at TOP-LEVEL scripts/ (v1.1 verify scripts), NOT demo/scripts/.
|
||||
set -u
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
fail() { echo "FAIL: $*" >&2; exit 1; }
|
||||
ok() { echo "ok: $*"; }
|
||||
|
||||
# --- Check 1: demo/ contains the full v1.0 demo tree ---
|
||||
for d in demo/modules demo/scripts demo/evidence-ui demo/contracts \
|
||||
demo/contracts-repo demo/.gitea/workflows; do
|
||||
[ -d "$d" ] || fail "missing $d"
|
||||
done
|
||||
[ -f demo/ACDL_DEMO.md ] || fail "missing demo/ACDL_DEMO.md"
|
||||
[ -f demo/scripts/run_demo.sh ] || fail "missing demo/scripts/run_demo.sh"
|
||||
ok "demo/ contains the full v1.0 demo"
|
||||
|
||||
# --- Check 2: regression - the archived demo still runs from demo/ ---
|
||||
out=$(ACDL_GITEA_TOKEN= bash demo/scripts/run_demo.sh --no-upload 2>&1); rc=$?
|
||||
[ "$rc" -eq 0 ] || { echo "$out" >&2; fail "demo/scripts/run_demo.sh --no-upload exited $rc"; }
|
||||
ok "demo/scripts/run_demo.sh --no-upload exits 0"
|
||||
|
||||
# --- Check 3: new top-level dirs exist and are scaffolded ---
|
||||
for d in platform schemas adapters terraform modules-ir; do
|
||||
[ -d "$d" ] || fail "missing new top-level dir $d"
|
||||
[ -f "$d/.gitkeep" ] || fail "missing $d/.gitkeep"
|
||||
done
|
||||
ok "new top-level dirs exist: platform/ schemas/ adapters/ terraform/ modules-ir/"
|
||||
|
||||
# --- Check 4: no stray v1.0 dirs left at repo root ---
|
||||
for stray in modules evidence-ui contracts contracts-repo ACDL_DEMO.md; do
|
||||
[ -e "$stray" ] && fail "stray $stray left at repo root (should be under demo/)"
|
||||
done
|
||||
[ -e ".gitea" ] && fail "stray .gitea/ left at repo root (moved to demo/.gitea/)"
|
||||
ok "no stray v1.0 dirs at repo root"
|
||||
|
||||
# --- Check 5: README reflects the real platform ---
|
||||
grep -q "Agentic Cloud Delivery Platform" README.md || fail "README missing platform name"
|
||||
grep -q "demo/" README.md || fail "README does not reference the archived demo/"
|
||||
grep -qi "vision\|architecture" README.md || fail "README missing vision/architecture links"
|
||||
ok "README reflects the real platform (name + demo/ ref + vision/arch links)"
|
||||
|
||||
echo "Phase 06: ALL CHECKS PASS"
|
||||
Reference in New Issue
Block a user