Compare commits
20 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 | ||
|
grimacing
|
0672edfc3f | ||
|
Jon Chery
|
1415c85d35 | ||
|
grimacing
|
72b359c9a9 | ||
|
Jon Chery
|
711b61d63e | ||
|
grimacing
|
3ea36ef3ab | ||
|
Jon Chery
|
6e27df7404 |
+273
-118
@@ -1,146 +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 |
|
||||
### 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).
|
||||
|
||||
## Data Flow
|
||||
- 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.
|
||||
|
||||
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.
|
||||
### 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.
|
||||
|
||||
## Build Order
|
||||
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.
|
||||
|
||||
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.
|
||||
### 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.
|
||||
|
||||
## Gitea API Surface (Phase 01 research)
|
||||
### 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.
|
||||
|
||||
Authoritative findings from the Gitea docs (added in RESEARCH; supersedes any
|
||||
GitHub-Pages / GitHub-Environments assumptions carried over from the spec):
|
||||
Environment progression:
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
### Branch pinning rule
|
||||
**Staging is removed.** Dev is the only autonomous environment.
|
||||
|
||||
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.
|
||||
## Cross-cutting concerns
|
||||
|
||||
### Default verification toolchain
|
||||
### 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.
|
||||
|
||||
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.
|
||||
### 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.
|
||||
|
||||
## L1 module schema (Phase 02 research)
|
||||
### 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.
|
||||
|
||||
Each L1 module lives at `modules/l1/<name>/` with exactly two files:
|
||||
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.
|
||||
|
||||
- `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.
|
||||
**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).
|
||||
|
||||
### L1 list (fixed per REQ-02 / D-019)
|
||||
### 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.
|
||||
|
||||
| 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 |
|
||||
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).
|
||||
|
||||
L1 modules are single-purpose, substrate-agnostic, max-depth-1 (per
|
||||
PROJECT.md Constraints). They do not compose with other L1s.
|
||||
### 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.
|
||||
|
||||
Reviewer routing: GitHub CODEOWNERS + Environment required reviewers
|
||||
(qa → QA; prod → SRE; dr → SRE). CODEOWNERS routes, does not enforce
|
||||
identity distinctness.
|
||||
|
||||
**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.
|
||||
|
||||
Full 8-concern attestation matrix (functional, performance, security
|
||||
posture, contract NFRs, operational readiness, incident response,
|
||||
capacity/cost, resilience) — see `docs/architecture.md` §10.4.
|
||||
|
||||
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.
|
||||
|
||||
### 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).
|
||||
|
||||
### 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.
|
||||
|
||||
**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.
|
||||
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
State storage: S3 (state) + DynamoDB (locking), cloud-managed,
|
||||
single-region in v1.
|
||||
|
||||
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.
|
||||
|
||||
**Policy result normalization (§12.6):** the confidence signal consumes a
|
||||
normalized `PolicyCheckResult` schema, not raw engine output.
|
||||
|
||||
```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, opaque to the signal..." },
|
||||
"resourceRef": "IR-typed resource identifier"
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## v1.1 spike scope
|
||||
|
||||
The spike (Phases 08–10) materializes the **minimum** that proves the IR
|
||||
commitments hold (no polyglot mess):
|
||||
|
||||
- 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).
|
||||
|
||||
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.
|
||||
|
||||
## 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:** false
|
||||
- **Reason:** No UI in Phases 01-04. The single UI artifact (`index.html`, vanilla JS) is built in Phase 05. frontend-engineer is reactivated for Phase 05 only (see Phase-specific overrides below).
|
||||
- **Phase-specific:** true (reactivates in Phase 05)
|
||||
- **Frameworks:** vanilla-js, dom-api, fetch-api
|
||||
- **Constraints:** no-frameworks, single-file, fetch-from-same-origin-raw-url
|
||||
- **Territory:** `acdl-evidence/index.html` (Phase 05)
|
||||
|
||||
## 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.
|
||||
+422
-54
@@ -1,85 +1,453 @@
|
||||
---
|
||||
phase: 02
|
||||
name: l1-modules
|
||||
milestone: v1.0
|
||||
phase: 6
|
||||
name: archive-demo-and-reorient
|
||||
milestone: v1.1
|
||||
milestone_type: feature
|
||||
status: planned
|
||||
requirements: [REQ-02, REQ-03]
|
||||
requirements: [] # Phase 06 introduces NO new REQ — it is repo hygiene (ROADMAP §Phase 06).
|
||||
must_haves:
|
||||
- "All 8 L1 module folders exist under modules/l1/ with the exact names from REQ-02"
|
||||
- "Each L1 has a manifest.yaml matching the schema in ARCHITECTURE.md (name, kind: l1, description, inputs: map of string keys)"
|
||||
- "Each L1 has a mock_apply.sh that echoes '[L1: <name>] applying...', sleeps 1s, echoes '[L1: <name>] OK', exits 0 (D-007)"
|
||||
- "All mock_apply.sh are executable (chmod +x) and bash -n clean"
|
||||
- "All manifest.yaml files parse as valid YAML"
|
||||
- "scripts/verify_phase02.sh passes: enumerates 8 L1s, validates each manifest, runs each mock_apply.sh, confirms exit 0 + expected output"
|
||||
- "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 modules/l1/*/mock_apply.sh scripts/*.sh && python3 -c 'import yaml; [yaml.safe_load(open(f)) for f in glob.glob(\"modules/l1/*/manifest.yaml\")]'"
|
||||
test: "scripts/verify_phase02.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 02 — l1-modules PLAN
|
||||
# Phase 06 — archive-demo-and-reorient PLAN
|
||||
|
||||
## Goal
|
||||
|
||||
Create the 8 L1 stub modules under `modules/l1/`. Each module has a
|
||||
`manifest.yaml` (declared inputs, flat string map per D-017) and a uniform
|
||||
`mock_apply.sh` (echo + 1s sleep + exit 0 per D-007/D-018). After this phase,
|
||||
Phase 03 can compose L1s into L2 modules and `mock_executor.sh` can iterate
|
||||
over an L2's L1 references.
|
||||
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-02: 8 L1 module folders exist (exact names)
|
||||
- REQ-03: each L1 has manifest.yaml + mock_apply.sh with the uniform behavior
|
||||
**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)
|
||||
**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 — infra-stub-engineer (creates the 8 L1s)
|
||||
**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-2.1** Create `modules/l1/l1-eks-fargate/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.2** Create `modules/l1/l1-iam-role/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.3** Create `modules/l1/l1-lambda/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.4** Create `modules/l1/l1-api-gateway/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.5** Create `modules/l1/l1-eventbridge/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.6** Create `modules/l1/l1-sqs/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.7** Create `modules/l1/l1-s3/{manifest.yaml, mock_apply.sh}`
|
||||
- **T-2.8** Create `modules/l1/l1-cloudwatch/{manifest.yaml, mock_apply.sh}`
|
||||
Domain priority order from `PERSONAS.md`:
|
||||
`coordination → security → platform → backend → frontend`.
|
||||
|
||||
Each L1's `manifest.yaml` declares 1-3 plausible inputs for that primitive
|
||||
(e.g., `l1-s3` declares `bucket_name`, `region`, `retention_days`; `l1-iam-role`
|
||||
declares `role_name`, `trust_policy`). Each `mock_apply.sh` follows the exact
|
||||
uniform template from ARCHITECTURE.md.
|
||||
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.
|
||||
|
||||
**Files owned (territory):** `modules/l1/**`
|
||||
Three waves, strictly ordered (each wave's tasks depend on the prior
|
||||
wave completing):
|
||||
|
||||
**Commits:** one per task, `---ci---` block has `phase: 2, status: plan-as-execute, persona: infra-stub-engineer, task: T-2.x, requirements.covered: [REQ-02, REQ-03]`.
|
||||
---
|
||||
|
||||
### Wave 2 — lead-developer (verification script + traceability)
|
||||
### Wave 1 — lead-developer: file moves + new layout + README + verify script
|
||||
|
||||
**Tasks:**
|
||||
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).
|
||||
|
||||
- **T-2.9** Create `scripts/verify_phase02.sh`. It:
|
||||
1. Enumerates `modules/l1/*/` and confirms exactly 8 folders with the 8 expected names.
|
||||
2. For each L1: confirms `manifest.yaml` exists and parses as YAML with `name` matching the folder, `kind: l1`, and an `inputs:` map.
|
||||
3. For each L1: confirms `mock_apply.sh` is executable, `bash -n` clean, runs in <2s, exits 0, and its stdout contains the `[L1: <name>] applying...` and `[L1: <name>] OK` markers.
|
||||
4. Prints a PASS/FAIL summary; exits 0 on full success.
|
||||
- **T-2.10** Update `.ciagent/REQUIREMENTS.md` (REQ-02/03 → covered pending VERIFY) and `.ciagent/ROADMAP.md` (Phase 02 → executing). No README change.
|
||||
#### T-6.1 — Move the v1.0 demo tree into `demo/`
|
||||
|
||||
**Files owned (territory):** `scripts/verify_phase02.sh`, `.ciagent/REQUIREMENTS.md`, `.ciagent/ROADMAP.md`
|
||||
- **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 per task, `---ci---` block has `phase: 2, status: plan-as-execute, persona: lead-developer, task: T-2.9/2.10`.
|
||||
```bash
|
||||
# From the repo root (/root/acdl). All moves via `git mv` to preserve history.
|
||||
# 1. Create the demo/ container.
|
||||
mkdir -p demo
|
||||
|
||||
## Wave ordering
|
||||
# 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)
|
||||
|
||||
- Wave 1 (infra-stub-engineer) creates all 8 L1s. A single subagent gets all 8 tasks; it commits per task.
|
||||
- Wave 2 (lead-developer) adds the verify script and traceability after the L1s exist.
|
||||
# 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.)
|
||||
|
||||
`backend-engineer`, `data-engineer`, `frontend-engineer` have 0 tasks this phase.
|
||||
# 4. Sanity: no empty stray dirs remain at repo root.
|
||||
# (git mv removes the source dir when it becomes empty; verify with `ls`.)
|
||||
```
|
||||
|
||||
**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`)
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
#### T-6.2 — Scaffold the new v1.1 top-level dirs (empty, .gitkeep'd)
|
||||
|
||||
- **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 Phase 01 (the `modules/l1/.gitkeep` from T-1.1 is replaced by real folders).
|
||||
- Phase 03 depends on this phase for L1 references in L2 compositions.
|
||||
- **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
-59
@@ -2,80 +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-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.
|
||||
+70
-15
@@ -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,20 +90,40 @@
|
||||
|
||||
## Traceability
|
||||
|
||||
### v1.0 (prior — demo)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-01 | 1 | complete (v1.0.1) |
|
||||
| REQ-02 | 2 | covered (pending VERIFY) |
|
||||
| REQ-03 | 2 | covered (pending VERIFY) |
|
||||
| REQ-04 | 3 | pending |
|
||||
| REQ-05 | 3 | pending |
|
||||
| REQ-06 | 3 | pending |
|
||||
| REQ-07 | 3 | pending |
|
||||
| REQ-08 | 3 | pending |
|
||||
| REQ-02 | 2 | complete (v1.0.2) |
|
||||
| REQ-03 | 2 | complete (v1.0.2) |
|
||||
| REQ-04 | 3 | complete (v1.0.3) |
|
||||
| REQ-05 | 3 | complete (v1.0.3) |
|
||||
| REQ-06 | 3 | complete (v1.0.3) |
|
||||
| REQ-07 | 3 | complete (v1.0.3) |
|
||||
| REQ-08 | 3 | complete (v1.0.3) |
|
||||
| REQ-09 | 1 | complete (v1.0.1) |
|
||||
| REQ-10 | 4 | partial (skeleton in Phase 01 v1.0.1; full impl in Phase 04) |
|
||||
| REQ-11 | 3 | pending |
|
||||
| REQ-12 | 4 | partial (skeleton in Phase 01 v1.0.1; full impl in Phase 04) |
|
||||
| REQ-13 | 5 | pending |
|
||||
| REQ-14 | 5 | pending |
|
||||
| REQ-15 | 5 | pending |
|
||||
| REQ-10 | 4 | complete (v1.0.4) |
|
||||
| REQ-11 | 3 | complete (v1.0.3) |
|
||||
| REQ-12 | 4 | complete (v1.0.4) |
|
||||
| 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
+81
-6
@@ -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
|
||||
|
||||
@@ -18,7 +29,7 @@ Five-phase breakdown to take ACDL from empty repo to a reproducible 4-act execut
|
||||
|
||||
### Phase 02 — l1-modules
|
||||
- **Description:** Create all 8 L1 module folders under `acdl/modules/l1/`, each with `manifest.yaml` (declared inputs) and `mock_apply.sh` (uniform echo + 1s sleep + exit 0).
|
||||
- **Status:** executing
|
||||
- **Status:** complete (v1.0.2)
|
||||
- **Depends on:** [1]
|
||||
- **Requirements:** REQ-02, REQ-03
|
||||
- **Success Criteria:**
|
||||
@@ -27,7 +38,7 @@ Five-phase breakdown to take ACDL from empty repo to a reproducible 4-act execut
|
||||
|
||||
### Phase 03 — l2-modules-and-core-scripts
|
||||
- **Description:** Create the 4 L2 compositions under `acdl/modules/l2/` referencing L1s, plus the 5 core scripts in `acdl/scripts/` (`mock_executor.sh`, `policy_checker.py`, `confidence_signal.py`, `evidence_writer.py`, `l3b_agent_stub.py`).
|
||||
- **Status:** not_started
|
||||
- **Status:** complete (v1.0.3)
|
||||
- **Depends on:** [2]
|
||||
- **Requirements:** REQ-04, REQ-05, REQ-06, REQ-07
|
||||
- **Success Criteria:**
|
||||
@@ -39,7 +50,7 @@ Five-phase breakdown to take ACDL from empty repo to a reproducible 4-act execut
|
||||
|
||||
### Phase 04 — pipeline-and-approval-gates
|
||||
- **Description:** Build the reusable pipeline workflow in `acdl/.gitea/workflows/` (Dev → QA → Prod → Finalize) plus the issue-triggered L3B workflow in `acdl-contracts/.gitea/workflows/`. Wire environment protection for QA and Prod.
|
||||
- **Status:** not_started
|
||||
- **Status:** complete (v1.0.4)
|
||||
- **Depends on:** [3]
|
||||
- **Requirements:** REQ-08, REQ-09, REQ-10, REQ-12
|
||||
- **Success Criteria:**
|
||||
@@ -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:** not_started
|
||||
- **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"
|
||||
}
|
||||
],
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
# ACDL reusable pipeline workflow (Phase 01 skeleton).
|
||||
#
|
||||
# This workflow is called from acdl-contracts via:
|
||||
# uses: continuous-intelligence/acdl/.gitea/workflows/pipeline.yml@milestone/v1.0-initial
|
||||
#
|
||||
# Branch pinning rule (see .ciagent/ARCHITECTURE.md): the `acdl` repo's default
|
||||
# branch is `milestone/v1.0-initial`, so `uses:` references must pin to
|
||||
# `@milestone/v1.0-initial`, NOT `@main`.
|
||||
#
|
||||
# Phase 04 will implement the actual stage logic + approval gates (D-013:
|
||||
# Gitea has no environments API; gates become workflow_dispatch approval
|
||||
# inputs).
|
||||
name: acdl-pipeline
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
contract-ref:
|
||||
description: "Ref on acdl-contracts that triggered the pipeline"
|
||||
required: false
|
||||
type: string
|
||||
default: main
|
||||
|
||||
jobs:
|
||||
dev:
|
||||
name: "Dev (autonomous)"
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# Phase 04 will implement: checkout acdl + acdl-contracts, run
|
||||
# policy_checker.py, mock_executor.sh, confidence_signal.py, write
|
||||
# evidence via evidence_writer.py.
|
||||
- name: "Dev stage placeholder"
|
||||
run: |
|
||||
echo "Dev stage placeholder (Phase 01 skeleton)"
|
||||
echo "Phase 04 will run policy_checker, mock_executor, confidence_signal, evidence_writer"
|
||||
exit 0
|
||||
|
||||
qa-gate:
|
||||
name: "QA (manual approval)"
|
||||
needs: dev
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# Phase 04 will implement: gate via workflow_dispatch approval input
|
||||
# (D-013 fallback; Gitea ignores jobs.<id>.environment).
|
||||
- name: "QA gate placeholder"
|
||||
run: |
|
||||
echo "QA gate placeholder (Phase 01 skeleton)"
|
||||
echo "Phase 04 will pause here for human approval via workflow_dispatch"
|
||||
exit 0
|
||||
|
||||
prod-gate:
|
||||
name: "Prod (manual approval)"
|
||||
needs: qa-gate
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# Phase 04 will implement: same approval-input gate as qa-gate.
|
||||
- name: "Prod gate placeholder"
|
||||
run: |
|
||||
echo "Prod gate placeholder (Phase 01 skeleton)"
|
||||
echo "Phase 04 will pause here for human approval via workflow_dispatch"
|
||||
exit 0
|
||||
|
||||
finalize:
|
||||
name: "Finalize (publish evidence)"
|
||||
needs: prod-gate
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# Phase 04/05 will implement: commit audit.json to acdl-evidence main
|
||||
# via the Gitea file-contents API; raw URL republishes index.html +
|
||||
# audit.json for the timeline UI (D-012).
|
||||
- name: "Finalize placeholder"
|
||||
run: |
|
||||
echo "Finalize placeholder (Phase 01 skeleton)"
|
||||
echo "Phase 04/05 will commit audit.json to acdl-evidence main"
|
||||
exit 0
|
||||
+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.
|
||||
@@ -1,40 +0,0 @@
|
||||
# ACDL issue-to-contract workflow (Phase 01 skeleton, reference copy).
|
||||
#
|
||||
# This file is the source-of-truth copy kept in the `acdl` repo under
|
||||
# contracts-repo/.gitea/workflows/. Phase 04 will push it to the actual
|
||||
# `acdl-contracts` repo under .gitea/workflows/ and implement the real
|
||||
# step bodies.
|
||||
#
|
||||
# Trigger: a new Issue is opened in acdl-contracts. The workflow runs
|
||||
# l3b_agent_stub.py to map the Issue body to a contract.yaml, commits the
|
||||
# contract to a new branch, closes the Issue, and triggers the main
|
||||
# pipeline in the `acdl` repo via the workflow_dispatch API (D-014; Gitea
|
||||
# Actions does not support repository_dispatch).
|
||||
name: issue-to-contract
|
||||
|
||||
on:
|
||||
issues:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
parse-and-trigger:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# Phase 04 will implement:
|
||||
# 1. checkout acdl-contracts (so l3b_agent_stub.py is available).
|
||||
# 2. run: python3 scripts/l3b_agent_stub.py "${{ gitea.event.issue.body }}" > contract.yaml
|
||||
# 3. parse the generated contract; commit it to a new branch
|
||||
# (e.g. contract/<issue-number>).
|
||||
# 4. push the branch.
|
||||
# 5. close the Issue with a comment linking to the pipeline run.
|
||||
# 6. trigger the main pipeline:
|
||||
# curl -X POST \
|
||||
# -H "Authorization: token ${GITEA_TOKEN}" \
|
||||
# https://git.cloudinit.dev/api/v1/repos/continuous-intelligence/acdl/actions/workflows/<id>/dispatches \
|
||||
# -d '{"ref":"milestone/v1.0-initial","inputs":{"contract-ref":"<branch>"}}'
|
||||
- name: "Issue-trigger placeholder"
|
||||
run: |
|
||||
echo "issue-to-contract placeholder (Phase 01 skeleton)"
|
||||
echo "Issue body: ${{ gitea.event.issue.body }}"
|
||||
echo "Phase 04 will run l3b_agent_stub.py, commit contract.yaml, close issue, dispatch pipeline"
|
||||
exit 0
|
||||
@@ -0,0 +1,153 @@
|
||||
# ACDL pipeline workflow (Phase 04 implementation).
|
||||
#
|
||||
# 3-dispatch approval-gate topology (D-027 / D-028; ARCHITECTURE.md
|
||||
# "Phase 04 pipeline topology"):
|
||||
#
|
||||
# Dispatch 1 (initial): approve_qa=false, approve_prod=false
|
||||
# -> runs the `dev` job (policy check, confidence
|
||||
# gate, mock_executor, evidence + finalize).
|
||||
# Dispatch 2 (QA approve): approve_qa=true, approve_prod=false
|
||||
# -> runs the `qa-gate` job (records QA approval
|
||||
# in the audit chain via evidence_writer +
|
||||
# finalize_evidence).
|
||||
# Dispatch 3 (Prod approve): approve_prod=true
|
||||
# -> runs the `prod-gate` job, then the `finalize`
|
||||
# job (needs: prod-gate) which writes the final
|
||||
# evidence event and commits audit.json to
|
||||
# acdl-evidence.
|
||||
#
|
||||
# Gitea Actions limitations driving this design:
|
||||
# - No `repository_dispatch` trigger (D-014).
|
||||
# - No environments API / `environment:` blocks are ignored (D-013).
|
||||
# - Re-dispatch starts a NEW run; artifacts do NOT survive between runs,
|
||||
# so state is persisted to acdl-evidence via the file-contents API
|
||||
# (D-028 / finalize_evidence.py) instead of via artifacts.
|
||||
#
|
||||
# Branch-pin rule (ARCHITECTURE.md "Branch pinning rule"):
|
||||
# This workflow lives on `acdl`'s default branch `milestone/v1.0-initial`.
|
||||
# Cross-repo `uses:` references (e.g. the issue-trigger's checkout of
|
||||
# l3b_agent_stub.py) MUST pin to `@milestone/v1.0-initial`, NOT `@main`
|
||||
# (the `acdl` repo has no `main` branch). This workflow is invoked via
|
||||
# the workflow_dispatch API (D-014), NOT via `workflow_call`, so the
|
||||
# `uses:` rule applies to the issue-trigger's checkout of the acdl repo,
|
||||
# not to this file itself.
|
||||
name: acdl-pipeline
|
||||
|
||||
"on":
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
contract-ref:
|
||||
description: "Ref on acdl-contracts that carries the contract"
|
||||
required: false
|
||||
type: string
|
||||
default: main
|
||||
approve_qa:
|
||||
description: "Human approval to advance past QA"
|
||||
required: false
|
||||
type: boolean
|
||||
default: false
|
||||
approve_prod:
|
||||
description: "Human approval to advance past Prod"
|
||||
required: false
|
||||
type: boolean
|
||||
default: false
|
||||
|
||||
jobs:
|
||||
dev:
|
||||
name: "Dev (autonomous)"
|
||||
if: inputs.approve_qa != true && inputs.approve_prod != true
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Checkout acdl-contracts at contract-ref"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: continuous-intelligence/acdl-contracts
|
||||
ref: ${{ inputs.contract-ref }}
|
||||
token: ${{ secrets.GITEA_TOKEN }}
|
||||
path: acdl-contracts
|
||||
|
||||
- name: "Policy check"
|
||||
run: |
|
||||
python3 scripts/policy_checker.py acdl-contracts/contract.yaml
|
||||
|
||||
- name: "Confidence signal"
|
||||
id: confidence
|
||||
run: |
|
||||
set +e
|
||||
SCORE_JSON=$(python3 scripts/confidence_signal.py acdl-contracts/contract.yaml)
|
||||
echo "$SCORE_JSON"
|
||||
echo "score_json=$SCORE_JSON" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: "Apply or reject based on confidence (gate < 0.50)"
|
||||
run: |
|
||||
set +e
|
||||
SCORE=$(python3 -c "import json,sys; print(json.load(sys.stdin)['score'])" <<< '${{ steps.confidence.outputs.score_json }}')
|
||||
python3 -c "import sys; sys.exit(0 if float('${SCORE}') >= 0.50 else 1)"
|
||||
THRESHOLD_RC=$?
|
||||
if [ "$THRESHOLD_RC" -ne 0 ]; then
|
||||
python3 scripts/evidence_writer.py --stage dev --event "dev rejected: confidence < 0.50" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
exit 1
|
||||
fi
|
||||
STACK=$(python3 -c 'import yaml; print(yaml.safe_load(open("acdl-contracts/contract.yaml"))["stack"])')
|
||||
bash scripts/mock_executor.sh acdl-contracts/contract.yaml
|
||||
python3 scripts/evidence_writer.py --stage dev --event "dev applied: ${STACK}" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
|
||||
- name: "Upload dev state artifacts (best-effort)"
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: dev-state
|
||||
path: |
|
||||
audit.json
|
||||
state.json
|
||||
|
||||
qa-gate:
|
||||
name: "QA (manual approval)"
|
||||
if: inputs.approve_qa == true && inputs.approve_prod != true
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Record QA approval in evidence"
|
||||
run: |
|
||||
python3 scripts/evidence_writer.py --stage qa --event "qa approved" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
|
||||
prod-gate:
|
||||
name: "Prod (manual approval)"
|
||||
if: inputs.approve_prod == true
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Record Prod approval in evidence"
|
||||
run: |
|
||||
python3 scripts/evidence_writer.py --stage prod --event "prod approved" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
|
||||
finalize:
|
||||
name: "Finalize (publish evidence)"
|
||||
needs: [prod-gate]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Write finalize event + commit audit.json to acdl-evidence"
|
||||
run: |
|
||||
python3 scripts/evidence_writer.py --stage finalize --event "pipeline complete: audit.json committed to acdl-evidence" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
@@ -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,145 @@
|
||||
# ACDL issue-to-contract workflow (Phase 04 implementation).
|
||||
#
|
||||
# Trigger: a new Issue is opened in acdl-contracts. The workflow runs
|
||||
# l3b_agent_stub.py (checked out from the `acdl` repo, pinned to
|
||||
# @milestone/v1.0-initial) to map the Issue body to a contract.yaml, commits
|
||||
# the contract to a new branch `contract/<issue-number>` on acdl-contracts
|
||||
# via the Gitea file-contents API, closes the Issue with a comment, and
|
||||
# dispatches the main pipeline in the `acdl` repo via the workflow_dispatch
|
||||
# API (D-014; Gitea Actions does not support repository_dispatch).
|
||||
#
|
||||
# Cross-repo trigger (D-014):
|
||||
# The final step POSTs to
|
||||
# /api/v1/repos/continuous-intelligence/acdl/actions/workflows/pipeline.yml/dispatches
|
||||
# with body {"ref": "milestone/v1.0-initial",
|
||||
# "inputs": {"contract-ref": "contract/<issue-number>"}}.
|
||||
#
|
||||
# Branch-pin rule (ARCHITECTURE.md):
|
||||
# The `acdl` repo's default branch is `milestone/v1.0-initial`, so the
|
||||
# checkout step pins `ref: milestone/v1.0-initial`. The pipeline dispatch
|
||||
# also pins `ref: milestone/v1.0-initial` (the workflow file lives on
|
||||
# that branch). The new `contract/<n>` branch is created on acdl-contracts
|
||||
# (whose default branch is `main`, per D-015).
|
||||
#
|
||||
# File-contents POST with `new_branch` (D-030):
|
||||
# The POST to /repos/.../contents/contract.yaml includes
|
||||
# `new_branch: contract/<n>`, which tells Gitea to create the file on a
|
||||
# NEW branch off the current head of `branch: main` instead of committing
|
||||
# directly to main. This avoids a separate branch-create + commit round
|
||||
# trip.
|
||||
name: issue-to-contract
|
||||
|
||||
"on":
|
||||
issues:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
parse-and-trigger:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (pinned to milestone/v1.0-initial for l3b_agent_stub.py)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: continuous-intelligence/acdl
|
||||
ref: milestone/v1.0-initial
|
||||
token: ${{ secrets.GITEA_TOKEN }}
|
||||
|
||||
- name: "Parse Issue body into contract.yaml"
|
||||
env:
|
||||
ISSUE_BODY: ${{ gitea.event.issue.body }}
|
||||
run: |
|
||||
# Pass the Issue body via an env var to avoid shell injection from
|
||||
# arbitrary Issue text. l3b_agent_stub.py reads argv[1]; we pass
|
||||
# the env var quoted so no metacharacter interpretation happens.
|
||||
python3 scripts/l3b_agent_stub.py "$ISSUE_BODY" -o contract.yaml
|
||||
echo "--- generated contract.yaml ---"
|
||||
cat contract.yaml
|
||||
|
||||
- name: "Commit contract.yaml to new branch contract/${{ gitea.event.issue.number }} on acdl-contracts"
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
STACK=$(python3 -c 'import yaml; print(yaml.safe_load(open("contract.yaml"))["stack"])')
|
||||
ISSUE_NUMBER="${{ gitea.event.issue.number }}"
|
||||
BRANCH="contract/${ISSUE_NUMBER}"
|
||||
HOST="https://git.cloudinit.dev"
|
||||
API="${HOST}/api/v1/repos/continuous-intelligence/acdl-contracts/contents/contract.yaml"
|
||||
B64=$(base64 -w 0 contract.yaml)
|
||||
BODY=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({
|
||||
'content': '${B64}',
|
||||
'message': 'l3b: contract for issue #${ISSUE_NUMBER}',
|
||||
'branch': 'main',
|
||||
'new_branch': '${BRANCH}'
|
||||
}))
|
||||
")
|
||||
STATUS=$(curl -sS -o /tmp/contract_post.json -w "%{http_code}" \
|
||||
-X POST \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$BODY" \
|
||||
"$API")
|
||||
echo "POST contract.yaml -> HTTP ${STATUS}"
|
||||
cat /tmp/contract_post.json || true
|
||||
case "$STATUS" in
|
||||
201) echo "contract.yaml committed on branch ${BRANCH}" ;;
|
||||
*) echo "ERROR: file-contents POST failed (HTTP ${STATUS})" >&2; exit 1 ;;
|
||||
esac
|
||||
echo "STACK=${STACK}" >> "$GITHUB_ENV"
|
||||
echo "BRANCH=${BRANCH}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: "Comment on Issue + close it"
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
ISSUE_NUMBER="${{ gitea.event.issue.number }}"
|
||||
HOST="https://git.cloudinit.dev"
|
||||
ISSUES_API="${HOST}/api/v1/repos/continuous-intelligence/acdl-contracts/issues/${ISSUE_NUMBER}"
|
||||
COMMENT_BODY=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({'body': 'Generated contract.yaml for stack \`' + '${STACK}' + '\` on branch \`' + '${BRANCH}' + '\`. Pipeline dispatched.'}))
|
||||
")
|
||||
curl -sS -o /tmp/comment.json -w "comment HTTP %{http_code}\n" \
|
||||
-X POST \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$COMMENT_BODY" \
|
||||
"${ISSUES_API}/comments"
|
||||
CLOSE_BODY='{"state":"closed"}'
|
||||
curl -sS -o /tmp/close.json -w "close HTTP %{http_code}\n" \
|
||||
-X PATCH \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$CLOSE_BODY" \
|
||||
"${ISSUES_API}"
|
||||
|
||||
- name: "Dispatch the pipeline on acdl (contract-ref = contract/${{ gitea.event.issue.number }})"
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
ISSUE_NUMBER="${{ gitea.event.issue.number }}"
|
||||
HOST="https://git.cloudinit.dev"
|
||||
DISPATCH_URL="${HOST}/api/v1/repos/continuous-intelligence/acdl/actions/workflows/pipeline.yml/dispatches"
|
||||
BODY=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({
|
||||
'ref': 'milestone/v1.0-initial',
|
||||
'inputs': {'contract-ref': 'contract/${ISSUE_NUMBER}'}
|
||||
}))
|
||||
")
|
||||
STATUS=$(curl -sS -o /tmp/dispatch.json -w "%{http_code}" \
|
||||
-X POST \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$BODY" \
|
||||
"$DISPATCH_URL")
|
||||
echo "pipeline dispatch -> HTTP ${STATUS}"
|
||||
cat /tmp/dispatch.json || true
|
||||
case "$STATUS" in
|
||||
201|202|204) echo "pipeline dispatched (contract-ref=contract/${ISSUE_NUMBER})" ;;
|
||||
*) echo "ERROR: pipeline dispatch failed (HTTP ${STATUS})" >&2; exit 1 ;;
|
||||
esac
|
||||
@@ -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,334 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>ACDL Evidence Timeline</title>
|
||||
<style>
|
||||
:root {
|
||||
--stage-dev: #2563eb;
|
||||
--stage-qa: #ca8a04;
|
||||
--stage-prod: #ea580c;
|
||||
--stage-finalize: #16a34a;
|
||||
--stage-genesis: #6b7280;
|
||||
--stage-rejected: #dc2626;
|
||||
--bg: #f8fafc;
|
||||
--card-bg: #ffffff;
|
||||
--text: #0f172a;
|
||||
--muted: #64748b;
|
||||
--border: #e2e8f0;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
html, body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
font-family: system-ui, -apple-system, sans-serif;
|
||||
line-height: 1.5;
|
||||
}
|
||||
header {
|
||||
padding: 24px 32px 16px;
|
||||
border-bottom: 1px solid var(--border);
|
||||
background: var(--card-bg);
|
||||
}
|
||||
header h1 {
|
||||
margin: 0 0 6px;
|
||||
font-size: 1.5rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
header p {
|
||||
margin: 0;
|
||||
color: var(--muted);
|
||||
font-size: 0.95rem;
|
||||
}
|
||||
.toolbar {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
padding: 16px 32px;
|
||||
background: var(--card-bg);
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
button#refresh {
|
||||
appearance: none;
|
||||
border: 1px solid var(--border);
|
||||
background: var(--text);
|
||||
color: #fff;
|
||||
padding: 8px 16px;
|
||||
border-radius: 6px;
|
||||
font-size: 0.9rem;
|
||||
font-family: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
button#refresh:hover { opacity: 0.9; }
|
||||
button#refresh:active { transform: translateY(1px); }
|
||||
.toolbar .status {
|
||||
color: var(--muted);
|
||||
font-size: 0.85rem;
|
||||
}
|
||||
main {
|
||||
padding: 24px 32px 48px;
|
||||
max-width: 900px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
.empty {
|
||||
padding: 48px 24px;
|
||||
text-align: center;
|
||||
color: var(--muted);
|
||||
background: var(--card-bg);
|
||||
border: 1px dashed var(--border);
|
||||
border-radius: 8px;
|
||||
}
|
||||
ol.timeline {
|
||||
list-style: none;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
position: relative;
|
||||
}
|
||||
ol.timeline::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 11px;
|
||||
top: 6px;
|
||||
bottom: 6px;
|
||||
width: 2px;
|
||||
background: var(--border);
|
||||
}
|
||||
li.event {
|
||||
position: relative;
|
||||
padding: 12px 0 12px 40px;
|
||||
}
|
||||
li.event::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 6px;
|
||||
top: 18px;
|
||||
width: 12px;
|
||||
height: 12px;
|
||||
border-radius: 50%;
|
||||
background: var(--dot, var(--muted));
|
||||
border: 2px solid var(--card-bg);
|
||||
box-shadow: 0 0 0 1px var(--border);
|
||||
}
|
||||
.card {
|
||||
background: var(--card-bg);
|
||||
border: 1px solid var(--border);
|
||||
border-left: 4px solid var(--dot, var(--muted));
|
||||
border-radius: 8px;
|
||||
padding: 12px 16px;
|
||||
}
|
||||
.card .row {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
.seq {
|
||||
display: inline-block;
|
||||
min-width: 28px;
|
||||
padding: 2px 6px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 600;
|
||||
text-align: center;
|
||||
border-radius: 4px;
|
||||
background: #eef2ff;
|
||||
color: #3730a3;
|
||||
border: 1px solid #c7d2fe;
|
||||
}
|
||||
.chip {
|
||||
display: inline-block;
|
||||
padding: 2px 8px;
|
||||
font-size: 0.72rem;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.04em;
|
||||
border-radius: 999px;
|
||||
color: #fff;
|
||||
background: var(--dot, var(--muted));
|
||||
}
|
||||
.ts {
|
||||
font-size: 0.8rem;
|
||||
color: var(--muted);
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
.event-text {
|
||||
margin: 4px 0 6px;
|
||||
font-size: 0.95rem;
|
||||
}
|
||||
.hash {
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 0.75rem;
|
||||
color: var(--muted);
|
||||
word-break: break-all;
|
||||
}
|
||||
footer {
|
||||
padding: 16px 32px 24px;
|
||||
border-top: 1px solid var(--border);
|
||||
color: var(--muted);
|
||||
font-size: 0.8rem;
|
||||
max-width: 900px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
footer code {
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
background: #f1f5f9;
|
||||
padding: 1px 4px;
|
||||
border-radius: 3px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<h1>ACDL Evidence Timeline</h1>
|
||||
<p>ACDL — Agentic Cloud Delivery Platform · Audit Timeline</p>
|
||||
</header>
|
||||
<div class="toolbar">
|
||||
<button id="refresh" type="button">Refresh</button>
|
||||
<span class="status" id="status"></span>
|
||||
</div>
|
||||
<main>
|
||||
<div id="container">
|
||||
<div class="empty">Loading…</div>
|
||||
</div>
|
||||
</main>
|
||||
<footer>
|
||||
<div id="footer"></div>
|
||||
</footer>
|
||||
<script>
|
||||
(function () {
|
||||
"use strict";
|
||||
|
||||
var AUDIT_URL = "./audit.json";
|
||||
var STAGE_COLORS = {
|
||||
dev: "var(--stage-dev)",
|
||||
qa: "var(--stage-qa)",
|
||||
prod: "var(--stage-prod)",
|
||||
finalize: "var(--stage-finalize)",
|
||||
genesis: "var(--stage-genesis)"
|
||||
};
|
||||
|
||||
function $(id) { return document.getElementById(id); }
|
||||
|
||||
function stageColor(stage, eventText) {
|
||||
var evt = (eventText || "").toString().toLowerCase();
|
||||
if (evt.indexOf("rejected") !== -1) {
|
||||
return "var(--stage-rejected)";
|
||||
}
|
||||
return STAGE_COLORS[stage] || "var(--stage-genesis)";
|
||||
}
|
||||
|
||||
function dash(v) {
|
||||
return (v === null || v === undefined || v === "") ? "—" : v;
|
||||
}
|
||||
|
||||
function hashPreview(hash) {
|
||||
if (hash === null || hash === undefined || hash === "") return "—";
|
||||
var s = String(hash);
|
||||
return s.slice(0, 12) + "…";
|
||||
}
|
||||
|
||||
function esc(s) {
|
||||
return String(s)
|
||||
.replace(/&/g, "&")
|
||||
.replace(/</g, "<")
|
||||
.replace(/>/g, ">")
|
||||
.replace(/"/g, """)
|
||||
.replace(/'/g, "'");
|
||||
}
|
||||
|
||||
function auditUrlDisplay() {
|
||||
try {
|
||||
var href = window.location.href;
|
||||
var slash = href.lastIndexOf("/");
|
||||
if (slash >= 0) {
|
||||
return href.slice(0, slash + 1) + "audit.json";
|
||||
}
|
||||
} catch (e) {}
|
||||
return AUDIT_URL;
|
||||
}
|
||||
|
||||
function renderEmpty(msg) {
|
||||
$("container").innerHTML =
|
||||
'<div class="empty">' + esc(msg) + "</div>";
|
||||
}
|
||||
|
||||
function renderTimeline(events) {
|
||||
if (!Array.isArray(events)) {
|
||||
renderEmpty("No audit data yet");
|
||||
return;
|
||||
}
|
||||
if (events.length === 0) {
|
||||
renderEmpty("No audit data yet");
|
||||
return;
|
||||
}
|
||||
var sorted = events.slice().sort(function (a, b) {
|
||||
var sa = (a && typeof a.seq === "number") ? a.seq : 0;
|
||||
var sb = (b && typeof b.seq === "number") ? b.seq : 0;
|
||||
return sa - sb;
|
||||
});
|
||||
var html = '<ol class="timeline">';
|
||||
for (var i = 0; i < sorted.length; i++) {
|
||||
var e = sorted[i] || {};
|
||||
var stage = dash(e.stage);
|
||||
var color = stageColor(e.stage, e.event);
|
||||
html += '<li class="event" style="--dot:' + color + ';">';
|
||||
html += '<div class="card" style="--dot:' + color + ';">';
|
||||
html += '<div class="row">';
|
||||
html += '<span class="seq">#' + esc(dash(e.seq)) + "</span>";
|
||||
html += '<span class="chip">' + esc(stage) + "</span>";
|
||||
html += '<span class="ts">' + esc(dash(e.ts)) + "</span>";
|
||||
html += "</div>";
|
||||
html += '<div class="event-text">' + esc(dash(e.event)) + "</div>";
|
||||
html += '<div class="hash">' + esc(hashPreview(e.hash)) + "</div>";
|
||||
html += "</div>";
|
||||
html += "</li>";
|
||||
}
|
||||
html += "</ol>";
|
||||
$("container").innerHTML = html;
|
||||
}
|
||||
|
||||
function renderFooter(ok) {
|
||||
var when = new Date().toISOString();
|
||||
var url = auditUrlDisplay();
|
||||
var prefix = "Fetched at " + when + " · audit.json: ";
|
||||
$("footer").innerHTML =
|
||||
esc(prefix) + '<code>' + esc(url) + "</code>" +
|
||||
(ok ? "" : " (fetch failed)");
|
||||
}
|
||||
|
||||
function setStatus(msg) {
|
||||
$("status").textContent = msg || "";
|
||||
}
|
||||
|
||||
function fetchAudit() {
|
||||
setStatus("Fetching…");
|
||||
fetch(AUDIT_URL, { cache: "no-store" })
|
||||
.then(function (res) {
|
||||
if (!res.ok) {
|
||||
throw new Error("HTTP " + res.status);
|
||||
}
|
||||
return res.json();
|
||||
})
|
||||
.then(function (data) {
|
||||
if (!Array.isArray(data)) {
|
||||
throw new Error("not an array");
|
||||
}
|
||||
renderTimeline(data);
|
||||
renderFooter(true);
|
||||
setStatus("Loaded " + data.length + " event(s)");
|
||||
})
|
||||
.catch(function (err) {
|
||||
renderEmpty("No audit data yet");
|
||||
renderFooter(false);
|
||||
setStatus("Fetch failed: " + (err && err.message ? err.message : "error"));
|
||||
});
|
||||
}
|
||||
|
||||
$("refresh").addEventListener("click", fetchAudit);
|
||||
fetchAudit();
|
||||
})();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,27 @@
|
||||
name: l2-commodity-price-feed
|
||||
kind: l2
|
||||
description: Real-time commodity price ingestion from Platts
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
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
|
||||
- name: l1-api-gateway
|
||||
inputs:
|
||||
api_name: platts-price-api
|
||||
stage_name: dev
|
||||
- name: l1-eventbridge
|
||||
inputs:
|
||||
bus_name: price-events
|
||||
rule_name: price-publish-rule
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-price-archive
|
||||
region: us-east-1
|
||||
retention_days: "90"
|
||||
@@ -0,0 +1,27 @@
|
||||
name: l2-energy-analytics-api
|
||||
kind: l2
|
||||
description: Historical energy analytics query API
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: analytics-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-api-gateway
|
||||
inputs:
|
||||
api_name: energy-analytics-api
|
||||
stage_name: dev
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: analytics-query
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-analytics-data
|
||||
region: us-east-1
|
||||
retention_days: "2555"
|
||||
- name: l1-cloudwatch
|
||||
inputs:
|
||||
log_group_name: /acdl/analytics-api
|
||||
metric_namespace: acdl/analytics
|
||||
@@ -0,0 +1,27 @@
|
||||
name: l2-invoice-service
|
||||
kind: l2
|
||||
description: Billing and invoicing microservice for energy trades
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: invoice-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-iam-role
|
||||
inputs:
|
||||
role_name: invoice-service-role
|
||||
trust_policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"eks.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: invoice-generator
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-sqs
|
||||
inputs:
|
||||
queue_name: invoice-queue
|
||||
visibility_timeout: "60"
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-invoice-archive
|
||||
region: us-east-1
|
||||
retention_days: "365"
|
||||
@@ -0,0 +1,27 @@
|
||||
name: l2-regulatory-reporting
|
||||
kind: l2
|
||||
description: Regulatory compliance and reporting for energy trading
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: regulatory-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-iam-role
|
||||
inputs:
|
||||
role_name: regulatory-reporting-role
|
||||
trust_policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"eks.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: regulatory-reporter
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-sqs
|
||||
inputs:
|
||||
queue_name: regulatory-queue
|
||||
visibility_timeout: "120"
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-regulatory-archive
|
||||
region: us-east-1
|
||||
retention_days: "2555"
|
||||
Executable
+55
@@ -0,0 +1,55 @@
|
||||
#!/usr/bin/env python3
|
||||
"""confidence_signal.py — REQ-08 / D-024
|
||||
|
||||
Reads a contract.yaml, invokes policy_checker.py as a subprocess, and emits
|
||||
a deterministic JSON confidence score.
|
||||
|
||||
policy pass -> {"score": 0.90, "reason": "POLICY_PASS"}
|
||||
policy fail -> {"score": 0.40, "reason": "<violation code>"}
|
||||
|
||||
Exit 0 ALWAYS (per D-024): the pipeline decides the gate, not this script's
|
||||
exit code.
|
||||
|
||||
Input: argv[1] = path to a contract.yaml file.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if len(sys.argv) < 2:
|
||||
print("usage: confidence_signal.py <contract.yaml>", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
contract_path = sys.argv[1]
|
||||
|
||||
# Resolve policy_checker.py relative to this script so it works regardless
|
||||
# of cwd. Use python3 + script path (not ./) per the contract.
|
||||
here = os.path.dirname(os.path.abspath(__file__))
|
||||
policy_checker = os.path.join(here, "policy_checker.py")
|
||||
|
||||
proc = subprocess.run(
|
||||
["python3", policy_checker, contract_path],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
if proc.returncode == 0:
|
||||
score = "0.90"
|
||||
# POLICY_PASS is the expected stdout; strip any trailing whitespace.
|
||||
reason = proc.stdout.strip() or "POLICY_PASS"
|
||||
else:
|
||||
score = "0.40"
|
||||
# The violation code (e.g. "POLICY_VIOLATION:PUBLIC_INGRESS") is on stdout.
|
||||
reason = proc.stdout.strip() or "POLICY_VIOLATION:UNKNOWN"
|
||||
|
||||
# Emit with literal score (two-decimal form per the contract) and a quoted
|
||||
# reason. Constructed manually so json.dumps does not collapse 0.90 -> 0.9.
|
||||
print('{"score": ' + score + ', "reason": ' + json.dumps(reason) + '}')
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Executable
+123
@@ -0,0 +1,123 @@
|
||||
#!/usr/bin/env python3
|
||||
"""evidence_writer.py — REQ-11 / D-023 / D-005
|
||||
|
||||
Appends a hash-chained event to audit.json.
|
||||
|
||||
Each event: {"seq": N, "ts": <iso8601 UTC>, "stage": "...", "event": "...",
|
||||
"prev_hash": "<sha256 or GENESIS>", "hash": "<sha256 of canonical json of this event with hash empty>"}
|
||||
|
||||
Hash chain (D-023):
|
||||
1. Build event dict with hash = "" (empty string).
|
||||
2. canonical = json.dumps(event, sort_keys=True, separators=(",", ":"))
|
||||
3. hash = sha256(canonical.encode("utf-8")).hexdigest()
|
||||
4. event["hash"] = hash
|
||||
5. append to audit.json
|
||||
|
||||
Auto-genesis: if audit.json is empty/missing and --stage is not "genesis",
|
||||
a genesis event (seq 0, prev_hash "GENESIS") is inserted first.
|
||||
|
||||
Input:
|
||||
--stage <dev|qa|prod|finalize|genesis> (required)
|
||||
--event "<text>" (required)
|
||||
--audit <path> (optional, default ./audit.json)
|
||||
Output: stdout {"seq": N, "hash": "..."}
|
||||
Exit: 0 on success, 1 on I/O error.
|
||||
"""
|
||||
import argparse
|
||||
import datetime
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
|
||||
GENESIS_EVENT_TEXT = "audit log initialized"
|
||||
|
||||
|
||||
def now_iso8601_utc() -> str:
|
||||
return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
def compute_hash(event: dict) -> str:
|
||||
"""Compute the sha256 hash of an event using canonical JSON (D-023)."""
|
||||
tmp = dict(event)
|
||||
tmp["hash"] = ""
|
||||
canonical = json.dumps(tmp, sort_keys=True, separators=(",", ":"))
|
||||
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def make_event(seq: int, stage: str, event_text: str, prev_hash: str) -> dict:
|
||||
event = {
|
||||
"seq": seq,
|
||||
"ts": now_iso8601_utc(),
|
||||
"stage": stage,
|
||||
"event": event_text,
|
||||
"prev_hash": prev_hash,
|
||||
"hash": "",
|
||||
}
|
||||
event["hash"] = compute_hash(event)
|
||||
return event
|
||||
|
||||
|
||||
def load_audit(audit_path: str) -> list:
|
||||
if not os.path.exists(audit_path):
|
||||
return []
|
||||
try:
|
||||
with open(audit_path, "r", encoding="utf-8") as fh:
|
||||
data = json.load(fh)
|
||||
except (json.JSONDecodeError, ValueError):
|
||||
return []
|
||||
if not isinstance(data, list):
|
||||
return []
|
||||
return data
|
||||
|
||||
|
||||
def atomic_write(audit_path: str, data: list) -> None:
|
||||
tmp_path = audit_path + ".tmp"
|
||||
with open(tmp_path, "w", encoding="utf-8") as fh:
|
||||
json.dump(data, fh, indent=2)
|
||||
fh.write("\n")
|
||||
os.replace(tmp_path, audit_path)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Append a hash-chained event to audit.json")
|
||||
parser.add_argument("--stage", required=True,
|
||||
choices=["dev", "qa", "prod", "finalize", "genesis"])
|
||||
parser.add_argument("--event", required=True)
|
||||
parser.add_argument("--audit", default="./audit.json")
|
||||
args = parser.parse_args()
|
||||
|
||||
events = load_audit(args.audit)
|
||||
|
||||
# Auto-genesis: if the log is empty and the caller did not ask for a
|
||||
# genesis event, seed one first.
|
||||
if len(events) == 0 and args.stage != "genesis":
|
||||
genesis = make_event(seq=0, stage="genesis", event_text=GENESIS_EVENT_TEXT,
|
||||
prev_hash="GENESIS")
|
||||
events.append(genesis)
|
||||
|
||||
# Determine the new seq + prev_hash.
|
||||
if events:
|
||||
last = events[-1]
|
||||
seq = last["seq"] + 1
|
||||
prev_hash = last["hash"]
|
||||
else:
|
||||
seq = 0
|
||||
prev_hash = "GENESIS"
|
||||
|
||||
new_event = make_event(seq=seq, stage=args.stage, event_text=args.event,
|
||||
prev_hash=prev_hash)
|
||||
events.append(new_event)
|
||||
|
||||
try:
|
||||
atomic_write(args.audit, events)
|
||||
except OSError as exc:
|
||||
print(f"evidence_writer: I/O error: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
print(json.dumps({"seq": new_event["seq"], "hash": new_event["hash"]}))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Executable
+182
@@ -0,0 +1,182 @@
|
||||
#!/usr/bin/env python3
|
||||
"""finalize_evidence.py — REQ-10 / D-028 / D-029
|
||||
|
||||
Uploads (PUT or POST) a local `audit.json` to the `acdl-evidence` repo on
|
||||
Gitea via the file-contents API. Used by the pipeline workflow steps to
|
||||
persist the hash-chained audit trail to `acdl-evidence` between dispatches
|
||||
(D-028 state-persistence across re-dispatches; D-029 finalize step).
|
||||
|
||||
Uses only the Python standard library (urllib.request) so it has no
|
||||
external dependency on `requests`. Auth header: `Authorization: token <token>`.
|
||||
|
||||
Input (argv flags):
|
||||
--audit <path> (required) local audit.json file to upload
|
||||
--owner <org> (optional, default continuous-intelligence)
|
||||
--repo <name> (optional, default acdl-evidence)
|
||||
--branch <name> (optional, default main)
|
||||
--path <remote path> (optional, default audit.json) path in the repo
|
||||
--token-env <env var> (optional, default ACDL_GITEA_TOKEN)
|
||||
--host <url> (optional, default https://git.cloudinit.dev)
|
||||
--message <commit msg> (optional, default chore(evidence): update audit.json)
|
||||
|
||||
Behavior:
|
||||
1. Read the token from os.environ[token_env]. Missing -> stderr + exit 1.
|
||||
2. Read the local audit file; base64-encode it.
|
||||
3. GET the current file at .../contents/<path>?ref=<branch> to discover
|
||||
the existing `sha`. 200 -> capture sha (update mode). 404 -> no sha
|
||||
(create mode). Other errors -> exit 1.
|
||||
4. If sha set: PUT with body {content, message, branch, sha}.
|
||||
If no sha: POST with body {content, message, branch}.
|
||||
5. Print {"uploaded": true, "path": "<path>", "sha": "<new sha>"} to
|
||||
stdout and exit 0.
|
||||
6. On any HTTP error: print
|
||||
{"uploaded": false, "status": <code>, "body": "<body>"} to stdout
|
||||
and exit 1.
|
||||
"""
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
|
||||
def _request(method: str, url: str, token: str, body: dict = None):
|
||||
"""Perform an HTTP request with the Gitea auth header. Returns
|
||||
(status_code, response_body_text). Raises URLError on network failure."""
|
||||
data = None
|
||||
headers = {"Authorization": f"token {token}",
|
||||
"Accept": "application/json"}
|
||||
if body is not None:
|
||||
data = json.dumps(body).encode("utf-8")
|
||||
headers["Content-Type"] = "application/json"
|
||||
req = urllib.request.Request(url, data=data, method=method, headers=headers)
|
||||
try:
|
||||
with urllib.request.urlopen(req) as resp:
|
||||
return resp.getcode(), resp.read().decode("utf-8", "replace")
|
||||
except urllib.error.HTTPError as exc:
|
||||
# HTTPError carries the response body
|
||||
try:
|
||||
body_text = exc.read().decode("utf-8", "replace")
|
||||
except Exception:
|
||||
body_text = ""
|
||||
return exc.code, body_text
|
||||
except urllib.error.URLError as exc:
|
||||
# Network-level failure (connection refused, DNS, timeout). Return
|
||||
# a synthetic 0 status + the reason so callers can report cleanly
|
||||
# without a stack trace.
|
||||
return 0, f"URLError: {exc.reason}"
|
||||
|
||||
|
||||
def get_existing_sha(host: str, owner: str, repo: str, path: str,
|
||||
branch: str, token: str):
|
||||
"""Return (sha-or-None, error_status_or_None). On 200 returns the sha.
|
||||
On 404 returns (None, None). Other codes return (None, (status, body))."""
|
||||
qs = urllib.parse.urlencode({"ref": branch})
|
||||
url = f"{host}/api/v1/repos/{owner}/{repo}/contents/{path}?{qs}"
|
||||
status, body = _request("GET", url, token)
|
||||
if status == 200:
|
||||
try:
|
||||
data = json.loads(body)
|
||||
return data.get("sha"), None
|
||||
except (ValueError, TypeError):
|
||||
return None, (status, body)
|
||||
if status == 404:
|
||||
return None, None
|
||||
return None, (status, body)
|
||||
|
||||
|
||||
def upload(host: str, owner: str, repo: str, path: str, branch: str,
|
||||
message: str, content_b64: str, sha, token: str):
|
||||
"""PUT (update) or POST (create) the file. Returns (new_sha, None) on
|
||||
success or (None, (status, body)) on HTTP error."""
|
||||
url = f"{host}/api/v1/repos/{owner}/{repo}/contents/{path}"
|
||||
if sha:
|
||||
body = {"content": content_b64, "message": message,
|
||||
"branch": branch, "sha": sha}
|
||||
status, resp = _request("PUT", url, token, body)
|
||||
else:
|
||||
body = {"content": content_b64, "message": message, "branch": branch}
|
||||
status, resp = _request("POST", url, token, body)
|
||||
if status in (200, 201):
|
||||
try:
|
||||
data = json.loads(resp)
|
||||
# The file-contents API returns the new content object either at
|
||||
# top-level `content` (POST create) or `content` (PUT update).
|
||||
new_sha = None
|
||||
if isinstance(data, dict):
|
||||
content_obj = data.get("content") or data
|
||||
if isinstance(content_obj, dict):
|
||||
new_sha = content_obj.get("sha")
|
||||
return new_sha, None
|
||||
except (ValueError, TypeError):
|
||||
return None, None
|
||||
return None, (status, resp)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Upload a local audit.json to the acdl-evidence Gitea "
|
||||
"repo via the file-contents API (D-028/D-029).")
|
||||
parser.add_argument("--audit", required=True,
|
||||
help="Local audit.json file to upload")
|
||||
parser.add_argument("--owner", default="continuous-intelligence",
|
||||
help="Gitea org (default: continuous-intelligence)")
|
||||
parser.add_argument("--repo", default="acdl-evidence",
|
||||
help="Gitea repo (default: acdl-evidence)")
|
||||
parser.add_argument("--branch", default="main",
|
||||
help="Target branch (default: main)")
|
||||
parser.add_argument("--path", default="audit.json",
|
||||
help="Remote path in the repo (default: audit.json)")
|
||||
parser.add_argument("--token-env", default="ACDL_GITEA_TOKEN",
|
||||
help="Env var name holding the Gitea token "
|
||||
"(default: ACDL_GITEA_TOKEN)")
|
||||
parser.add_argument("--host", default="https://git.cloudinit.dev",
|
||||
help="Gitea host URL (default: https://git.cloudinit.dev)")
|
||||
parser.add_argument("--message", default="chore(evidence): update audit.json",
|
||||
help="Commit message (default: chore(evidence): "
|
||||
"update audit.json)")
|
||||
args = parser.parse_args()
|
||||
|
||||
token = os.environ.get(args.token_env)
|
||||
if not token:
|
||||
print(f"finalize_evidence: required env var {args.token_env} is not "
|
||||
f"set", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
# Read + base64-encode the local audit file. Missing/unreadable file is
|
||||
# a clean exit 1 (no stack trace).
|
||||
try:
|
||||
with open(args.audit, "rb") as fh:
|
||||
raw = fh.read()
|
||||
except OSError as exc:
|
||||
print(f"finalize_evidence: cannot read {args.audit}: {exc}",
|
||||
file=sys.stderr)
|
||||
return 1
|
||||
content_b64 = base64.b64encode(raw).decode("ascii")
|
||||
|
||||
# Discover existing sha (update vs create).
|
||||
sha, err = get_existing_sha(args.host, args.owner, args.repo,
|
||||
args.path, args.branch, token)
|
||||
if err is not None:
|
||||
status, body = err
|
||||
print(json.dumps({"uploaded": False, "status": status, "body": body}))
|
||||
return 1
|
||||
|
||||
# Upload (PUT if sha, POST otherwise).
|
||||
new_sha, err = upload(args.host, args.owner, args.repo, args.path,
|
||||
args.branch, args.message, content_b64, sha, token)
|
||||
if err is not None:
|
||||
status, body = err
|
||||
print(json.dumps({"uploaded": False, "status": status, "body": body}))
|
||||
return 1
|
||||
|
||||
print(json.dumps({"uploaded": True, "path": args.path,
|
||||
"sha": new_sha}))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Executable
+118
@@ -0,0 +1,118 @@
|
||||
#!/usr/bin/env python3
|
||||
"""l3b_agent_stub.py — D-008 / D-026 / D-021
|
||||
|
||||
Parses a GitHub/Gitea Issue body by keywords and emits a contract.yaml that
|
||||
selects an L2 stack. This is the agentic (L3B) entry surface: deterministic
|
||||
keyword matching, no external AI APIs.
|
||||
|
||||
D-008 keyword map (priority order — first match wins):
|
||||
gas, price, ingest, data-lake -> l2-commodity-price-feed
|
||||
invoice, billing -> l2-invoice-service
|
||||
analytics, historical, query -> l2-energy-analytics-api
|
||||
regulatory, compliance, reporting, trading
|
||||
-> l2-regulatory-reporting
|
||||
(no match) -> l2-invoice-service (fallback)
|
||||
|
||||
Output contract.yaml (D-021 schema):
|
||||
stack: <mapped L2 name>
|
||||
inputs:
|
||||
environment: dev
|
||||
owner: citizen-developer
|
||||
source: l3b-agent-stub
|
||||
public-ingress: false
|
||||
|
||||
Input:
|
||||
argv[1] = issue body text (or stdin if argv[1] absent/empty)
|
||||
-o <path> = write the contract to a file (default: stdout)
|
||||
Exit:
|
||||
0 on success, 1 on empty input
|
||||
"""
|
||||
import sys
|
||||
|
||||
|
||||
# Ordered keyword groups -> L2 stack mapping (D-008). First match wins.
|
||||
KEYWORD_MAP = [
|
||||
(("gas", "price", "ingest", "data-lake"), "l2-commodity-price-feed"),
|
||||
(("invoice", "billing"), "l2-invoice-service"),
|
||||
(("analytics", "historical", "query"), "l2-energy-analytics-api"),
|
||||
(("regulatory", "compliance", "reporting", "trading"), "l2-regulatory-reporting"),
|
||||
]
|
||||
|
||||
FALLBACK_STACK = "l2-invoice-service"
|
||||
|
||||
|
||||
def map_issue_to_stack(text: str) -> str:
|
||||
lowered = text.lower()
|
||||
for keywords, stack in KEYWORD_MAP:
|
||||
for kw in keywords:
|
||||
if kw in lowered:
|
||||
return stack
|
||||
return FALLBACK_STACK
|
||||
|
||||
|
||||
def render_contract(stack: str) -> str:
|
||||
# Fixed-schema YAML (D-021). Emitted as text (no yaml dependency needed).
|
||||
return (
|
||||
f"stack: {stack}\n"
|
||||
"inputs:\n"
|
||||
" environment: dev\n"
|
||||
" owner: citizen-developer\n"
|
||||
" source: l3b-agent-stub\n"
|
||||
"public-ingress: false\n"
|
||||
)
|
||||
|
||||
|
||||
def read_issue_body(args: list) -> str:
|
||||
"""Read issue body from args[0] (already-stripped argv, no script name)
|
||||
or stdin. Empty -> error."""
|
||||
if len(args) >= 1 and args[0].strip():
|
||||
return args[0]
|
||||
# Fall back to stdin if argv body is absent or empty.
|
||||
if not sys.stdin.isatty():
|
||||
data = sys.stdin.read()
|
||||
if data.strip():
|
||||
return data
|
||||
return ""
|
||||
|
||||
|
||||
def parse_output_flag(argv: list):
|
||||
"""Extract -o <path> from argv (returns (rest, output_path))."""
|
||||
output_path = None
|
||||
rest = []
|
||||
i = 1
|
||||
while i < len(argv):
|
||||
arg = argv[i]
|
||||
if arg == "-o":
|
||||
if i + 1 < len(argv):
|
||||
output_path = argv[i + 1]
|
||||
i += 2
|
||||
continue
|
||||
else:
|
||||
print("l3b_agent_stub: -o requires a path argument", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
rest.append(arg)
|
||||
i += 1
|
||||
return rest, output_path
|
||||
|
||||
|
||||
def main() -> int:
|
||||
rest, output_path = parse_output_flag(sys.argv)
|
||||
body = read_issue_body(rest)
|
||||
if not body.strip():
|
||||
print("l3b_agent_stub: empty issue body (no argv[1] and no stdin)", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
stack = map_issue_to_stack(body)
|
||||
contract = render_contract(stack)
|
||||
|
||||
if output_path:
|
||||
with open(output_path, "w", encoding="utf-8") as fh:
|
||||
fh.write(contract)
|
||||
else:
|
||||
sys.stdout.write(contract)
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Executable
+126
@@ -0,0 +1,126 @@
|
||||
#!/usr/bin/env bash
|
||||
# mock_executor.sh — REQ-06 / D-022
|
||||
#
|
||||
# Reads a contract.yaml, resolves the L2 composition, invokes each L1's
|
||||
# mock_apply.sh in order, and writes state.json to the current working
|
||||
# directory.
|
||||
#
|
||||
# Input: argv[1] = path to a contract.yaml file.
|
||||
# Output:
|
||||
# - stdout: per-L1 progress (echoed from each mock_apply.sh)
|
||||
# - state.json in cwd: {"l2": "...", "l1s": [...], "contract": {...}}
|
||||
# Exit:
|
||||
# 0 if all L1s exit 0; 1 if any L1 exited non-zero (state.json is still
|
||||
# written with the recorded exit codes).
|
||||
set -euo pipefail
|
||||
|
||||
if [[ $# -lt 1 ]]; then
|
||||
echo "usage: mock_executor.sh <contract.yaml>" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
CONTRACT_PATH="$1"
|
||||
|
||||
if [[ ! -f "$CONTRACT_PATH" ]]; then
|
||||
echo "contract not found: $CONTRACT_PATH" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Parse the contract (stack + full contract dict) via python3 + yaml. ---
|
||||
# Emit stack on line 1 and the full contract JSON on line 2, then read both
|
||||
# lines into separate bash variables (so the JSON's internal spaces survive).
|
||||
CONTRACT_PARSED=$(python3 - "$CONTRACT_PATH" <<'PY'
|
||||
import sys, json, yaml
|
||||
path = sys.argv[1]
|
||||
with open(path, "r", encoding="utf-8") as fh:
|
||||
contract = yaml.safe_load(fh)
|
||||
if not isinstance(contract, dict):
|
||||
sys.stderr.write("contract is not a mapping\n")
|
||||
sys.exit(2)
|
||||
stack = contract.get("stack", "")
|
||||
# Use a compact JSON (no spaces) so the single-line contract survives bash
|
||||
# variable capture cleanly.
|
||||
print(stack)
|
||||
print(json.dumps(contract, sort_keys=True, separators=(",", ":")))
|
||||
PY
|
||||
)
|
||||
|
||||
STACK=$(printf '%s\n' "$CONTRACT_PARSED" | sed -n '1p')
|
||||
CONTRACT_JSON=$(printf '%s\n' "$CONTRACT_PARSED" | sed -n '2p')
|
||||
|
||||
if [[ -z "$STACK" ]]; then
|
||||
echo "contract missing 'stack' key" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Resolve the L2 manifest. ---
|
||||
L2_MANIFEST="modules/l2/${STACK}/manifest.yaml"
|
||||
if [[ ! -f "$L2_MANIFEST" ]]; then
|
||||
echo "L2_NOT_FOUND: ${STACK}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Read the L2's l1s: list (ordered names) via python. ---
|
||||
L1_NAMES_JSON=$(python3 - "$L2_MANIFEST" <<'PY'
|
||||
import sys, json, yaml
|
||||
path = sys.argv[1]
|
||||
with open(path, "r", encoding="utf-8") as fh:
|
||||
manifest = yaml.safe_load(fh)
|
||||
l1s = manifest.get("l1s", []) if isinstance(manifest, dict) else []
|
||||
names = [entry.get("name", "") for entry in l1s if isinstance(entry, dict)]
|
||||
print(json.dumps(names))
|
||||
PY
|
||||
)
|
||||
|
||||
# --- Invoke each L1's mock_apply.sh in order, recording exit codes. ---
|
||||
# Build the l1s results array in JSON via python, appending as we go.
|
||||
RESULTS_JSON="[]"
|
||||
|
||||
ALL_OK=0
|
||||
while IFS= read -r L1_NAME; do
|
||||
L1_SCRIPT="modules/l1/${L1_NAME}/mock_apply.sh"
|
||||
if [[ ! -f "$L1_SCRIPT" ]]; then
|
||||
echo "L1_NOT_FOUND: ${L1_NAME}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Capture stdout + exit code. stderr passes through.
|
||||
L1_OUT=$(bash "$L1_SCRIPT")
|
||||
L1_RC=$?
|
||||
|
||||
# Echo the L1's stdout so the pipeline sees the progress lines.
|
||||
printf '%s\n' "$L1_OUT"
|
||||
|
||||
# Record {"name": ..., "applied": true, "exit_code": ...}.
|
||||
RESULTS_JSON=$(python3 - "$RESULTS_JSON" "$L1_NAME" "$L1_RC" <<'PY'
|
||||
import sys, json
|
||||
results = json.loads(sys.argv[1])
|
||||
name = sys.argv[2]
|
||||
rc = int(sys.argv[3])
|
||||
results.append({"name": name, "applied": True, "exit_code": rc})
|
||||
print(json.dumps(results))
|
||||
PY
|
||||
)
|
||||
|
||||
if [[ $L1_RC -ne 0 ]]; then
|
||||
ALL_OK=1
|
||||
fi
|
||||
done < <(python3 -c "import sys, json; print('\n'.join(json.loads(sys.argv[1])))" "$L1_NAMES_JSON")
|
||||
|
||||
# --- Write state.json to the current working directory (D-022). ---
|
||||
python3 - "$RESULTS_JSON" "$STACK" "$CONTRACT_JSON" <<'PY'
|
||||
import sys, json
|
||||
results = json.loads(sys.argv[1])
|
||||
stack = sys.argv[2]
|
||||
contract = json.loads(sys.argv[3])
|
||||
state = {
|
||||
"l2": stack,
|
||||
"l1s": results,
|
||||
"contract": contract,
|
||||
}
|
||||
with open("state.json", "w", encoding="utf-8") as fh:
|
||||
json.dump(state, fh, indent=2)
|
||||
fh.write("\n")
|
||||
PY
|
||||
|
||||
exit "$ALL_OK"
|
||||
Executable
+51
@@ -0,0 +1,51 @@
|
||||
#!/usr/bin/env python3
|
||||
"""policy_checker.py — REQ-07 / D-025
|
||||
|
||||
Reads a contract.yaml and enforces the single Phase-03 policy rule:
|
||||
`public-ingress: true` is forbidden.
|
||||
|
||||
Input: argv[1] = path to a contract.yaml file.
|
||||
Output: stdout "POLICY_PASS" or "POLICY_VIOLATION:PUBLIC_INGRESS"
|
||||
Exit: 0 on pass, 1 on violation.
|
||||
|
||||
Idempotent, no side effects (no file writes). Treats an absent or falsy
|
||||
`public-ingress` key as a pass.
|
||||
"""
|
||||
import sys
|
||||
import yaml
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if len(sys.argv) < 2:
|
||||
print("usage: policy_checker.py <contract.yaml>", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
contract_path = sys.argv[1]
|
||||
|
||||
try:
|
||||
with open(contract_path, "r", encoding="utf-8") as fh:
|
||||
contract = yaml.safe_load(fh)
|
||||
except FileNotFoundError:
|
||||
print(f"contract not found: {contract_path}", file=sys.stderr)
|
||||
return 2
|
||||
except yaml.YAMLError as exc:
|
||||
print(f"invalid yaml: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
# Treat missing/non-mapping as no policy violation.
|
||||
if not isinstance(contract, dict):
|
||||
print("POLICY_PASS")
|
||||
return 0
|
||||
|
||||
public_ingress = contract.get("public-ingress", False)
|
||||
|
||||
if public_ingress is True:
|
||||
print("POLICY_VIOLATION:PUBLIC_INGRESS")
|
||||
return 1
|
||||
|
||||
print("POLICY_PASS")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Executable
+258
@@ -0,0 +1,258 @@
|
||||
#!/usr/bin/env bash
|
||||
# scripts/run_demo.sh — Phase 05 dry-run simulation of the 4 demo acts (T-5.2).
|
||||
#
|
||||
# Simulates the full 4-act demo locally (no act_runner) by calling the core
|
||||
# scripts in sequence and writing hash-chained evidence events to audit.json,
|
||||
# then optionally uploads audit.json + evidence-ui/index.html to acdl-evidence
|
||||
# main via finalize_evidence.py (D-031, D-033).
|
||||
#
|
||||
# Usage: scripts/run_demo.sh [--no-upload]
|
||||
# --no-upload skip the Gitea API calls (useful for testing without a token)
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Parse args
|
||||
# -----------------------------------------------------------------------------
|
||||
UPLOAD=1
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--no-upload)
|
||||
UPLOAD=0
|
||||
;;
|
||||
*)
|
||||
echo "run_demo.sh: unknown argument: $arg" >&2
|
||||
echo "usage: scripts/run_demo.sh [--no-upload]" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Paths
|
||||
# -----------------------------------------------------------------------------
|
||||
# Repo root = location of this script's parent dir.
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
|
||||
WORKDIR="/tmp/acdl_demo_run"
|
||||
AUDIT="$WORKDIR/audit.json"
|
||||
CONTRACTS="$WORKDIR/contracts"
|
||||
|
||||
# Track failures so we can return non-zero at the end (we do NOT use set -e
|
||||
# because policy_checker intentionally exits 1 on Act 4).
|
||||
FAIL=0
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
# Write one evidence event. Args: <stage> <event-text>
|
||||
ev() {
|
||||
local stage="$1"
|
||||
local text="$2"
|
||||
if ! python3 "$SCRIPT_DIR/evidence_writer.py" --stage "$stage" --event "$text" --audit "$AUDIT"; then
|
||||
echo "run_demo.sh: evidence_writer failed for stage=$stage text=$text" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
}
|
||||
|
||||
# Run a contract through the Act 2/3 pipeline (policy -> confidence -> executor).
|
||||
# Assumes the contract already passed policy (caller verifies). Writes the
|
||||
# standard 4-event sequence. Args: <act-label> <dev-applied-event-text>
|
||||
run_passing_pipeline() {
|
||||
local dev_event="$1"
|
||||
|
||||
ev dev "$dev_event"
|
||||
ev qa "qa approved"
|
||||
ev prod "prod approved"
|
||||
ev finalize "finalize: audit.json committed to acdl-evidence"
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Setup working directory
|
||||
# -----------------------------------------------------------------------------
|
||||
mkdir -p "$CONTRACTS"
|
||||
rm -f "$AUDIT"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Initialize audit (genesis)
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== run_demo.sh: initializing audit at $AUDIT =="
|
||||
ev genesis "audit log initialized"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 1 — Friction
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 1 — Friction =="
|
||||
ev dev "Act 1 Friction: manual 2-week deployment (legacy process)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 2 — Developer Self-Service
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 2 — Developer Self-Service =="
|
||||
cat > "$CONTRACTS/act2.yaml" <<'YAML'
|
||||
stack: l2-commodity-price-feed
|
||||
inputs:
|
||||
environment: dev
|
||||
owner: platform-team
|
||||
public-ingress: false
|
||||
YAML
|
||||
|
||||
ACT2_POLICY="$(python3 "$SCRIPT_DIR/policy_checker.py" "$CONTRACTS/act2.yaml")"
|
||||
ACT2_POLICY_RC=$?
|
||||
echo " policy_checker: $ACT2_POLICY (rc=$ACT2_POLICY_RC)"
|
||||
if [ "$ACT2_POLICY" != "POLICY_PASS" ]; then
|
||||
echo "run_demo.sh: Act 2 expected POLICY_PASS, got '$ACT2_POLICY'" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
ACT2_CONF="$(python3 "$SCRIPT_DIR/confidence_signal.py" "$CONTRACTS/act2.yaml")"
|
||||
echo " confidence_signal: $ACT2_CONF"
|
||||
# Expected: {"score": 0.90, "reason": "POLICY_PASS"}
|
||||
|
||||
# mock_executor.sh resolves modules/l2/<stack>/manifest.yaml relative to its
|
||||
# cwd, so it must run from the repo root. It writes state.json to its cwd;
|
||||
# clean it up from the repo root afterward so no stray file is left there.
|
||||
(
|
||||
cd "$REPO_ROOT" && bash "$SCRIPT_DIR/mock_executor.sh" "$CONTRACTS/act2.yaml"
|
||||
)
|
||||
MOCK_RC=$?
|
||||
rm -f "$REPO_ROOT/state.json"
|
||||
if [ "$MOCK_RC" -ne 0 ]; then
|
||||
echo "run_demo.sh: Act 2 mock_executor failed (rc=$MOCK_RC)" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
run_passing_pipeline "dev applied: l2-commodity-price-feed"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 3 — Citizen Developer
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 3 — Citizen Developer =="
|
||||
ISSUE_BODY="We need to ingest natural gas prices from Platts and report on compliance for the trading desk."
|
||||
if ! python3 "$SCRIPT_DIR/l3b_agent_stub.py" "$ISSUE_BODY" -o "$CONTRACTS/act3.yaml"; then
|
||||
echo "run_demo.sh: l3b_agent_stub failed for Act 3" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
# Confirm the generated contract's stack (D-008: gas/price matches first).
|
||||
ACT3_STACK="$(python3 -c "import yaml,sys; print(yaml.safe_load(open('$CONTRACTS/act3.yaml'))['stack'])" 2>/dev/null || echo "")"
|
||||
echo " l3b generated stack: $ACT3_STACK"
|
||||
if [ "$ACT3_STACK" != "l2-commodity-price-feed" ]; then
|
||||
echo "run_demo.sh: WARNING Act 3 expected stack l2-commodity-price-feed, got '$ACT3_STACK'" >&2
|
||||
# Continue anyway per the task spec.
|
||||
fi
|
||||
|
||||
ACT3_POLICY="$(python3 "$SCRIPT_DIR/policy_checker.py" "$CONTRACTS/act3.yaml")"
|
||||
ACT3_POLICY_RC=$?
|
||||
echo " policy_checker: $ACT3_POLICY (rc=$ACT3_POLICY_RC)"
|
||||
if [ "$ACT3_POLICY" != "POLICY_PASS" ]; then
|
||||
echo "run_demo.sh: Act 3 expected POLICY_PASS, got '$ACT3_POLICY'" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
ACT3_CONF="$(python3 "$SCRIPT_DIR/confidence_signal.py" "$CONTRACTS/act3.yaml")"
|
||||
echo " confidence_signal: $ACT3_CONF"
|
||||
|
||||
(
|
||||
cd "$REPO_ROOT" && bash "$SCRIPT_DIR/mock_executor.sh" "$CONTRACTS/act3.yaml"
|
||||
)
|
||||
MOCK_RC=$?
|
||||
rm -f "$REPO_ROOT/state.json"
|
||||
if [ "$MOCK_RC" -ne 0 ]; then
|
||||
echo "run_demo.sh: Act 3 mock_executor failed (rc=$MOCK_RC)" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
run_passing_pipeline "dev applied: l2-commodity-price-feed (Act 3 from issue)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 4 — Safety Net
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 4 — Safety Net =="
|
||||
cat > "$CONTRACTS/act4.yaml" <<'YAML'
|
||||
stack: l2-regulatory-reporting
|
||||
inputs:
|
||||
environment: dev
|
||||
owner: platform-team
|
||||
public-ingress: true
|
||||
YAML
|
||||
|
||||
# policy_checker exits 1 on violation; capture without failing the script.
|
||||
ACT4_POLICY="$(python3 "$SCRIPT_DIR/policy_checker.py" "$CONTRACTS/act4.yaml" 2>&1 || true)"
|
||||
echo " policy_checker: $ACT4_POLICY"
|
||||
if [ "$ACT4_POLICY" != "POLICY_VIOLATION:PUBLIC_INGRESS" ]; then
|
||||
echo "run_demo.sh: Act 4 expected POLICY_VIOLATION:PUBLIC_INGRESS, got '$ACT4_POLICY'" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
ACT4_CONF="$(python3 "$SCRIPT_DIR/confidence_signal.py" "$CONTRACTS/act4.yaml")"
|
||||
echo " confidence_signal: $ACT4_CONF"
|
||||
# Expected: {"score": 0.40, "reason": "POLICY_VIOLATION:PUBLIC_INGRESS"}
|
||||
|
||||
# Score < 0.50 -> dev rejects. Do NOT run mock_executor, do NOT write qa/prod/finalize.
|
||||
ev dev "dev rejected: POLICY_VIOLATION:PUBLIC_INGRESS (confidence 0.40 < 0.50)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Summary
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Summary =="
|
||||
python3 - "$AUDIT" <<'PY'
|
||||
import json, sys
|
||||
audit = json.load(open(sys.argv[1]))
|
||||
for e in audit:
|
||||
print(f"{e['seq']} | {e['stage']} | {e['event']} | {e['hash'][:12]}")
|
||||
print(f"total events: {len(audit)}")
|
||||
PY
|
||||
|
||||
EVENT_COUNT="$(python3 -c "import json; print(len(json.load(open('$AUDIT'))))")"
|
||||
echo "event count: $EVENT_COUNT"
|
||||
|
||||
if [ "$EVENT_COUNT" -lt 11 ]; then
|
||||
echo "run_demo.sh: expected >= 11 events, got $EVENT_COUNT" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Upload (optional)
|
||||
# -----------------------------------------------------------------------------
|
||||
if [ "$UPLOAD" -eq 1 ]; then
|
||||
echo "== Upload =="
|
||||
if [ -z "${ACDL_GITEA_TOKEN:-}" ]; then
|
||||
echo "run_demo.sh: ACDL_GITEA_TOKEN not set; skipping upload (use --no-upload to silence)" >&2
|
||||
else
|
||||
# Upload audit.json to acdl-evidence main.
|
||||
if python3 "$SCRIPT_DIR/finalize_evidence.py" --audit "$AUDIT"; then
|
||||
echo " audit.json uploaded"
|
||||
else
|
||||
echo "run_demo.sh: finalize_evidence failed for audit.json" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
# Upload index.html (the --audit flag accepts any local file path; --path
|
||||
# sets the remote destination).
|
||||
if python3 "$SCRIPT_DIR/finalize_evidence.py" \
|
||||
--audit "$REPO_ROOT/evidence-ui/index.html" \
|
||||
--path index.html \
|
||||
--message "chore(ui): update index.html (demo dry run)"; then
|
||||
echo " index.html uploaded"
|
||||
else
|
||||
echo "run_demo.sh: finalize_evidence failed for index.html" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
echo "Uploaded audit.json + index.html to acdl-evidence main"
|
||||
echo " raw URL: https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html"
|
||||
fi
|
||||
else
|
||||
echo "== Upload skipped (--no-upload) =="
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Exit
|
||||
# -----------------------------------------------------------------------------
|
||||
if [ "$FAIL" -ne 0 ]; then
|
||||
echo "run_demo.sh: one or more steps failed (see warnings above)" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "run_demo.sh: OK ($EVENT_COUNT events)"
|
||||
exit 0
|
||||
Executable
+240
@@ -0,0 +1,240 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 03 verification script.
|
||||
# Confirms the 4 L2 modules and the 5 core scripts conform to their contracts.
|
||||
#
|
||||
# Usage: scripts/verify_phase03.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
# Expected L2 names per REQ-04.
|
||||
EXPECTED_L2S=(
|
||||
l2-invoice-service
|
||||
l2-commodity-price-feed
|
||||
l2-energy-analytics-api
|
||||
l2-regulatory-reporting
|
||||
)
|
||||
|
||||
echo "== Phase 03 verification =="
|
||||
echo "Root: ${ROOT}"
|
||||
echo
|
||||
|
||||
# --- Check 1: exactly 4 L2 folders with the expected names ---
|
||||
echo "-- Check 1: 4 L2 folders with expected names --"
|
||||
actual=$(ls modules/l2/ 2>/dev/null | sort | tr '\n' ' ')
|
||||
expected=$(printf '%s\n' "${EXPECTED_L2S[@]}" | sort | tr '\n' ' ')
|
||||
if [ "$actual" = "$expected" ]; then
|
||||
pass "exactly 4 L2 folders present and named correctly"
|
||||
else
|
||||
fail "L2 folder list mismatch"
|
||||
echo " expected: $expected"
|
||||
echo " actual: $actual"
|
||||
fi
|
||||
|
||||
# --- Check 2: each L2 manifest.yaml validates + references 5 existing L1s ---
|
||||
echo "-- Check 2: L2 manifests reference 5 existing L1s --"
|
||||
l2_validate=$(python3 << 'PYEOF' || true
|
||||
import yaml, glob, os, sys
|
||||
ok = True
|
||||
l1s = set(os.listdir('modules/l1'))
|
||||
for f in sorted(glob.glob('modules/l2/*/manifest.yaml')):
|
||||
d = yaml.safe_load(open(f))
|
||||
folder = os.path.basename(os.path.dirname(f))
|
||||
problems = []
|
||||
if d.get('name') != folder: problems.append(f"name != {folder}")
|
||||
if d.get('kind') != 'l2': problems.append("kind != l2")
|
||||
refs = [x.get('name') for x in d.get('l1s', [])]
|
||||
if len(refs) != 5: problems.append(f"expected 5 l1s, got {len(refs)}")
|
||||
unknown = [r for r in refs if r not in l1s]
|
||||
if unknown: problems.append(f"unknown L1 refs: {unknown}")
|
||||
# each l1 entry must have an inputs: map
|
||||
for x in d.get('l1s', []):
|
||||
if not isinstance(x.get('inputs'), dict): problems.append(f"l1 {x.get('name')} missing inputs map")
|
||||
status = 'OK' if not problems else 'FAIL: ' + '; '.join(problems)
|
||||
print(f' [{status}] {f}')
|
||||
if problems: ok = False
|
||||
sys.exit(0 if ok else 1)
|
||||
PYEOF
|
||||
)
|
||||
echo "$l2_validate"
|
||||
if [ "$l2_validate" = "" ] || echo "$l2_validate" | grep -q FAIL; then
|
||||
if ! echo "$l2_validate" | grep -q PASS; then
|
||||
fail "one or more L2 manifests invalid (see above)"
|
||||
fi
|
||||
else
|
||||
pass "all 4 L2 manifests valid"
|
||||
fi
|
||||
# Re-run for the explicit pass/fail count
|
||||
python3 << 'PYEOF' > /tmp/l2_check.txt 2>&1 || true
|
||||
import yaml, glob, os, sys
|
||||
ok = True
|
||||
l1s = set(os.listdir('modules/l1'))
|
||||
for f in sorted(glob.glob('modules/l2/*/manifest.yaml')):
|
||||
d = yaml.safe_load(open(f))
|
||||
folder = os.path.basename(os.path.dirname(f))
|
||||
if d.get('name') != folder: ok = False
|
||||
if d.get('kind') != 'l2': ok = False
|
||||
refs = [x.get('name') for x in d.get('l1s', [])]
|
||||
if len(refs) != 5: ok = False
|
||||
if any(r not in l1s for r in refs): ok = False
|
||||
for x in d.get('l1s', []):
|
||||
if not isinstance(x.get('inputs'), dict): ok = False
|
||||
sys.exit(0 if ok else 1)
|
||||
PYEOF
|
||||
if [ $? -eq 0 ]; then pass "all 4 L2 manifests pass structural + reference checks"; else fail "L2 manifest structural check"; fi
|
||||
|
||||
# --- Check 3: typecheck (bash -n + py_compile + yaml load) ---
|
||||
echo "-- Check 3: typecheck --"
|
||||
if bash -n scripts/mock_executor.sh; then pass "bash -n mock_executor.sh"; else fail "bash -n mock_executor.sh"; fi
|
||||
if python3 -m py_compile scripts/policy_checker.py scripts/confidence_signal.py scripts/evidence_writer.py scripts/l3b_agent_stub.py 2>/dev/null; then
|
||||
pass "py_compile all 4 python scripts"
|
||||
else
|
||||
fail "py_compile"
|
||||
fi
|
||||
if python3 -c "import yaml, glob; [yaml.safe_load(open(f)) for f in glob.glob('modules/l2/*/manifest.yaml')]" 2>/dev/null; then
|
||||
pass "yaml load all L2 manifests"
|
||||
else
|
||||
fail "yaml load L2 manifests"
|
||||
fi
|
||||
|
||||
# --- Check 4: policy_checker (D-025) ---
|
||||
echo "-- Check 4: policy_checker behavior (D-025) --"
|
||||
WORK="$(mktemp -d)"
|
||||
trap 'rm -rf "$WORK" "$ROOT/tmp_pass_contract.yaml" "$ROOT/tmp_fail_contract.yaml" "$ROOT/state.json" 2>/dev/null || true' EXIT
|
||||
printf 'stack: l2-commodity-price-feed\npublic-ingress: false\n' > "$WORK/pass.yaml"
|
||||
printf 'stack: l2-regulatory-reporting\npublic-ingress: true\n' > "$WORK/fail.yaml"
|
||||
out=$(python3 scripts/policy_checker.py "$WORK/pass.yaml" 2>&1); rc=$?
|
||||
if [ "$out" = "POLICY_PASS" ] && [ "$rc" = "0" ]; then
|
||||
pass "policy_checker pass contract -> POLICY_PASS exit 0"
|
||||
else
|
||||
fail "policy_checker pass contract: got '$out' exit=$rc"
|
||||
fi
|
||||
out=$(python3 scripts/policy_checker.py "$WORK/fail.yaml" 2>&1); rc=$?
|
||||
if [ "$out" = "POLICY_VIOLATION:PUBLIC_INGRESS" ] && [ "$rc" = "1" ]; then
|
||||
pass "policy_checker fail contract -> POLICY_VIOLATION:PUBLIC_INGRESS exit 1"
|
||||
else
|
||||
fail "policy_checker fail contract: got '$out' exit=$rc"
|
||||
fi
|
||||
|
||||
# --- Check 5: confidence_signal (D-024) ---
|
||||
echo "-- Check 5: confidence_signal behavior (D-024) --"
|
||||
out=$(python3 scripts/confidence_signal.py "$WORK/pass.yaml" 2>&1); rc=$?
|
||||
if echo "$out" | grep -q '"score": 0.90' && [ "$rc" = "0" ]; then
|
||||
pass "confidence_signal pass -> score 0.90 exit 0"
|
||||
else
|
||||
fail "confidence_signal pass: got '$out' exit=$rc"
|
||||
fi
|
||||
out=$(python3 scripts/confidence_signal.py "$WORK/fail.yaml" 2>&1); rc=$?
|
||||
if echo "$out" | grep -q '"score": 0.40' && [ "$rc" = "0" ]; then
|
||||
pass "confidence_signal fail -> score 0.40 exit 0"
|
||||
else
|
||||
fail "confidence_signal fail: got '$out' exit=$rc"
|
||||
fi
|
||||
|
||||
# --- Check 6: evidence_writer hash chain (D-023) ---
|
||||
echo "-- Check 6: evidence_writer hash chain (D-023) --"
|
||||
rm -f "$WORK/audit.json"
|
||||
python3 scripts/evidence_writer.py --stage dev --event "dev start" --audit "$WORK/audit.json" > /dev/null
|
||||
python3 scripts/evidence_writer.py --stage qa --event "qa approved" --audit "$WORK/audit.json" > /dev/null
|
||||
python3 scripts/evidence_writer.py --stage prod --event "prod approved" --audit "$WORK/audit.json" > /dev/null
|
||||
chain_ok=$(python3 << PYEOF
|
||||
import json, hashlib, sys
|
||||
try:
|
||||
events = json.load(open("$WORK/audit.json"))
|
||||
assert len(events) == 4, f"expected 4 (genesis + 3), got {len(events)}"
|
||||
assert events[0]['prev_hash'] == 'GENESIS', "genesis prev_hash"
|
||||
for i in range(1, len(events)):
|
||||
assert events[i]['prev_hash'] == events[i-1]['hash'], f"chain break at {i}"
|
||||
e = dict(events[i]); h = e.pop('hash'); e['hash'] = ''
|
||||
canon = json.dumps(e, sort_keys=True, separators=(',',':'))
|
||||
assert hashlib.sha256(canon.encode()).hexdigest() == h, f"hash mismatch at {i}"
|
||||
print("OK")
|
||||
except AssertionError as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$chain_ok" = "OK" ]; then
|
||||
pass "evidence_writer: 4 events, GENESIS + 3, chain links + hashes valid"
|
||||
else
|
||||
fail "evidence_writer chain: $chain_ok"
|
||||
fi
|
||||
|
||||
# --- Check 7: mock_executor (D-022) ---
|
||||
echo "-- Check 7: mock_executor writes state.json (D-022) --"
|
||||
rm -f "$ROOT/state.json"
|
||||
out=$(bash scripts/mock_executor.sh "$WORK/pass.yaml" 2>&1); rc=$?
|
||||
if [ "$rc" != "0" ]; then
|
||||
fail "mock_executor exit $rc (expected 0)"
|
||||
else
|
||||
me_ok=$(python3 << PYEOF
|
||||
import json, sys
|
||||
try:
|
||||
s = json.load(open("$ROOT/state.json"))
|
||||
assert s['l2'] == 'l2-commodity-price-feed', f"l2 mismatch: {s.get('l2')}"
|
||||
assert 'l1s' in s and len(s['l1s']) == 5, f"expected 5 l1s, got {len(s.get('l1s', []))}"
|
||||
assert all(x['applied'] is True and x['exit_code'] == 0 for x in s['l1s']), "l1 not all applied+0"
|
||||
assert 'contract' in s, "missing contract field"
|
||||
print("OK")
|
||||
except Exception as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$me_ok" = "OK" ]; then
|
||||
pass "mock_executor: state.json with l2 + 5 l1s (all exit 0) + contract"
|
||||
else
|
||||
fail "mock_executor state.json: $me_ok"
|
||||
fi
|
||||
fi
|
||||
rm -f "$ROOT/state.json"
|
||||
|
||||
# --- Check 8: l3b_agent_stub D-008 keyword map ---
|
||||
echo "-- Check 8: l3b_agent_stub keyword map (D-008) --"
|
||||
act3=$(python3 scripts/l3b_agent_stub.py "We need to ingest natural gas prices from Platts and report on compliance." 2>&1)
|
||||
if echo "$act3" | grep -q 'stack: l2-commodity-price-feed'; then
|
||||
pass "l3b Act 3 example -> l2-commodity-price-feed"
|
||||
else
|
||||
fail "l3b Act 3 example: got '$act3'"
|
||||
fi
|
||||
fallback=$(python3 scripts/l3b_agent_stub.py "please deploy something" 2>&1)
|
||||
if echo "$fallback" | grep -q 'stack: l2-invoice-service'; then
|
||||
pass "l3b fallback (no keywords) -> l2-invoice-service"
|
||||
else
|
||||
fail "l3b fallback: got '$fallback'"
|
||||
fi
|
||||
regulatory=$(python3 scripts/l3b_agent_stub.py "regulatory compliance reporting for trading desk" 2>&1)
|
||||
if echo "$regulatory" | grep -q 'stack: l2-regulatory-reporting'; then
|
||||
pass "l3b regulatory keywords -> l2-regulatory-reporting"
|
||||
else
|
||||
fail "l3b regulatory: got '$regulatory'"
|
||||
fi
|
||||
invoice=$(python3 scripts/l3b_agent_stub.py "monthly invoice and billing reconciliation" 2>&1)
|
||||
if echo "$invoice" | grep -q 'stack: l2-invoice-service'; then
|
||||
pass "l3b invoice keywords -> l2-invoice-service"
|
||||
else
|
||||
fail "l3b invoice: got '$invoice'"
|
||||
fi
|
||||
analytics=$(python3 scripts/l3b_agent_stub.py "historical analytics and query API" 2>&1)
|
||||
if echo "$analytics" | grep -q 'stack: l2-energy-analytics-api'; then
|
||||
pass "l3b analytics keywords -> l2-energy-analytics-api"
|
||||
else
|
||||
fail "l3b analytics: got '$analytics'"
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 03 verification PASSED (4 L2s + 5 core scripts, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 03 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
Executable
+186
@@ -0,0 +1,186 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 04 verification script.
|
||||
# Confirms the pipeline workflow + issue trigger + finalize_evidence.py
|
||||
# conform to the Phase 04 plan and the Gitea Actions topology in
|
||||
# ARCHITECTURE.md. Does NOT execute a real Gitea Actions run (act_runner
|
||||
# is not registered in this environment); validates structure + syntax
|
||||
# + a dry-run of finalize_evidence.py against a dead host.
|
||||
#
|
||||
# Usage: scripts/verify_phase04.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
echo "== Phase 04 verification =="
|
||||
echo "Root: ${ROOT}"
|
||||
echo
|
||||
|
||||
# --- Check 1: typecheck ---
|
||||
echo "-- Check 1: typecheck --"
|
||||
if bash -n scripts/finalize_evidence.py 2>/dev/null || python3 -m py_compile scripts/finalize_evidence.py 2>/dev/null; then
|
||||
pass "py_compile finalize_evidence.py"
|
||||
else
|
||||
fail "py_compile finalize_evidence.py"
|
||||
fi
|
||||
if python3 -c "import yaml; yaml.safe_load(open('.gitea/workflows/pipeline.yml')); yaml.safe_load(open('contracts-repo/.gitea/workflows/issue-to-contract.yml'))" 2>/dev/null; then
|
||||
pass "yaml load both workflows"
|
||||
else
|
||||
fail "yaml load workflows"
|
||||
fi
|
||||
|
||||
# --- Check 2: pipeline.yml structure ---
|
||||
echo "-- Check 2: pipeline.yml structure (D-027, D-028) --"
|
||||
p_struct=$(python3 << 'PYEOF'
|
||||
import yaml, sys
|
||||
try:
|
||||
d = yaml.safe_load(open('.gitea/workflows/pipeline.yml'))
|
||||
on = d.get('on', d.get(True)) or {}
|
||||
assert 'workflow_dispatch' in on, 'no workflow_dispatch trigger'
|
||||
inputs = on['workflow_dispatch']['inputs']
|
||||
assert set(inputs.keys()) == {'contract-ref', 'approve_qa', 'approve_prod'}, f'inputs: {set(inputs.keys())}'
|
||||
assert inputs['contract-ref']['type'] == 'string', 'contract-ref type'
|
||||
assert inputs['approve_qa']['type'] == 'boolean', 'approve_qa type'
|
||||
assert inputs['approve_prod']['type'] == 'boolean', 'approve_prod type'
|
||||
jobs = d['jobs']
|
||||
assert set(jobs.keys()) == {'dev', 'qa-gate', 'prod-gate', 'finalize'}, f'jobs: {set(jobs.keys())}'
|
||||
dev_if = jobs['dev'].get('if', '')
|
||||
assert 'approve_qa' in dev_if and 'approve_prod' in dev_if, f'dev.if: {dev_if}'
|
||||
qa_if = jobs['qa-gate'].get('if', '')
|
||||
assert 'approve_qa' in qa_if, f'qa-gate.if: {qa_if}'
|
||||
prod_if = jobs['prod-gate'].get('if', '')
|
||||
assert 'approve_prod' in prod_if, f'prod-gate.if: {prod_if}'
|
||||
fin_needs = jobs['finalize'].get('needs', [])
|
||||
assert fin_needs == ['prod-gate'] or fin_needs == 'prod-gate', f'finalize.needs: {fin_needs}'
|
||||
# All jobs runs-on ubuntu-latest
|
||||
for name, job in jobs.items():
|
||||
assert job.get('runs-on') == 'ubuntu-latest', f'{name} runs-on: {job.get("runs-on")}'
|
||||
print('OK')
|
||||
except AssertionError as ex:
|
||||
print(f'FAIL: {ex}')
|
||||
sys.exit(1)
|
||||
except Exception as ex:
|
||||
print(f'FAIL: {ex}')
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$p_struct" = "OK" ]; then
|
||||
pass "pipeline.yml: 3 inputs + 4 jobs + correct if: conditions + finalize.needs=prod-gate"
|
||||
else
|
||||
fail "pipeline.yml structure: $p_struct"
|
||||
fi
|
||||
|
||||
# --- Check 3: pipeline.yml references core scripts ---
|
||||
echo "-- Check 3: pipeline.yml references core scripts (D-029) --"
|
||||
text=$(cat .gitea/workflows/pipeline.yml)
|
||||
missing=""
|
||||
for ref in policy_checker.py confidence_signal.py mock_executor.sh evidence_writer.py finalize_evidence.py; do
|
||||
if ! echo "$text" | grep -qF "$ref"; then
|
||||
missing="$missing $ref"
|
||||
fi
|
||||
done
|
||||
if [ -z "$missing" ]; then
|
||||
pass "pipeline.yml references all 5 core scripts"
|
||||
else
|
||||
fail "pipeline.yml missing references:$missing"
|
||||
fi
|
||||
# Branch-pin documentation
|
||||
if echo "$text" | grep -q 'milestone/v1.0-initial'; then
|
||||
pass "pipeline.yml documents branch-pin to milestone/v1.0-initial"
|
||||
else
|
||||
fail "pipeline.yml missing branch-pin reference"
|
||||
fi
|
||||
|
||||
# --- Check 4: issue-to-contract.yml structure ---
|
||||
echo "-- Check 4: issue-to-contract.yml structure (D-030) --"
|
||||
i_struct=$(python3 << 'PYEOF'
|
||||
import yaml, sys
|
||||
try:
|
||||
d = yaml.safe_load(open('contracts-repo/.gitea/workflows/issue-to-contract.yml'))
|
||||
on = d.get('on', d.get(True)) or {}
|
||||
assert 'issues' in on, 'no issues trigger'
|
||||
assert on['issues']['types'] == ['opened'], f'types: {on["issues"]["types"]}'
|
||||
assert 'parse-and-trigger' in d['jobs'], 'no parse-and-trigger job'
|
||||
assert d['jobs']['parse-and-trigger'].get('runs-on') == 'ubuntu-latest', 'runs-on'
|
||||
print('OK')
|
||||
except AssertionError as ex:
|
||||
print(f'FAIL: {ex}')
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$i_struct" = "OK" ]; then
|
||||
pass "issue-to-contract.yml: issues[opened] + parse-and-trigger job"
|
||||
else
|
||||
fail "issue-to-contract.yml structure: $i_struct"
|
||||
fi
|
||||
|
||||
# --- Check 5: issue-to-contract.yml references + dispatch endpoint ---
|
||||
echo "-- Check 5: issue-to-contract.yml references + dispatch (D-014, D-030) --"
|
||||
text=$(cat contracts-repo/.gitea/workflows/issue-to-contract.yml)
|
||||
missing=""
|
||||
for ref in l3b_agent_stub.py 'actions/workflows/pipeline.yml/dispatches' 'contract-ref' 'gitea.event.issue.number' 'GITEA_TOKEN' 'new_branch'; do
|
||||
if ! echo "$text" | grep -qF "$ref"; then
|
||||
missing="$missing $ref"
|
||||
fi
|
||||
done
|
||||
if [ -z "$missing" ]; then
|
||||
pass "issue-to-contract.yml: l3b_agent_stub + dispatch + contract-ref + issue number + token + new_branch"
|
||||
else
|
||||
fail "issue-to-contract.yml missing references:$missing"
|
||||
fi
|
||||
|
||||
# --- Check 6: finalize_evidence.py --help + clean failure ---
|
||||
echo "-- Check 6: finalize_evidence.py CLI + clean failure modes ---"
|
||||
out=$(python3 scripts/finalize_evidence.py --help 2>&1); rc=$?
|
||||
if [ "$rc" = "0" ] && echo "$out" | grep -qi 'usage\|--audit\|--owner'; then
|
||||
pass "finalize_evidence.py --help exits 0 with usage"
|
||||
else
|
||||
fail "finalize_evidence.py --help: rc=$rc"
|
||||
fi
|
||||
|
||||
# Missing audit file (with a fake token so it gets past the env check) → exit 1, no stack trace
|
||||
out=$(ACDL_GITEA_TOKEN=fake python3 scripts/finalize_evidence.py --audit /tmp/definitely_nonexistent_audit.json 2>&1); rc=$?
|
||||
if [ "$rc" = "1" ] && ! echo "$out" | grep -q 'Traceback'; then
|
||||
pass "finalize_evidence.py missing file → exit 1, no stack trace"
|
||||
else
|
||||
fail "finalize_evidence.py missing file: rc=$rc, out='$out'"
|
||||
fi
|
||||
|
||||
# Missing token env (audit file present) → exit 1, no stack trace
|
||||
printf '[]\n' > /tmp/empty_audit.json
|
||||
out=$(env -u ACDL_GITEA_TOKEN python3 scripts/finalize_evidence.py --audit /tmp/empty_audit.json 2>&1); rc=$?
|
||||
if [ "$rc" = "1" ] && ! echo "$out" | grep -q 'Traceback'; then
|
||||
pass "finalize_evidence.py missing token env → exit 1, no stack trace"
|
||||
else
|
||||
fail "finalize_evidence.py missing token: rc=$rc, out='$out'"
|
||||
fi
|
||||
|
||||
# --- Check 7: finalize_evidence.py dry-run against a dead host (clean failure) ---
|
||||
echo "-- Check 7: finalize_evidence.py dry-run against dead host ---"
|
||||
# Use a real audit.json but point at a host that will refuse the connection.
|
||||
printf '[{"seq":0,"ts":"2026-07-21T00:00:00Z","stage":"genesis","event":"init","prev_hash":"GENESIS","hash":"x"}]\n' > /tmp/real_audit.json
|
||||
out=$(ACDL_GITEA_TOKEN=fake GITEA_HOST=http://127.0.0.1:0 python3 scripts/finalize_evidence.py --audit /tmp/real_audit.json --host http://127.0.0.1:0 2>&1); rc=$?
|
||||
if [ "$rc" = "1" ] && ! echo "$out" | grep -q 'Traceback'; then
|
||||
pass "finalize_evidence.py dead host → exit 1, no stack trace (clean API failure)"
|
||||
else
|
||||
fail "finalize_evidence.py dead host: rc=$rc, out='$out'"
|
||||
fi
|
||||
|
||||
# Cleanup
|
||||
rm -f /tmp/empty_audit.json /tmp/real_audit.json
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 04 verification PASSED (pipeline + issue trigger + finalize helper, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 04 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
Executable
+213
@@ -0,0 +1,213 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 05 verification script.
|
||||
# Validates the evidence UI + the 4-act demo dry-run.
|
||||
#
|
||||
# Usage: scripts/verify_phase05.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
GITEA_HOST="${GITEA_HOST:-https://git.cloudinit.dev}"
|
||||
ORG="continuous-intelligence"
|
||||
EVIDENCE_REPO="acdl-evidence"
|
||||
|
||||
echo "== Phase 05 verification =="
|
||||
echo "Root: ${ROOT}"
|
||||
echo
|
||||
|
||||
# --- Check 1: evidence-ui/index.html structure ---
|
||||
echo "-- Check 1: evidence-ui/index.html structure (D-032, REQ-14) --"
|
||||
UI="evidence-ui/index.html"
|
||||
if [ ! -f "$UI" ]; then
|
||||
fail "$UI missing"
|
||||
else
|
||||
pass "$UI exists"
|
||||
size=$(wc -c < "$UI")
|
||||
if [ "$size" -ge 1000 ] && [ "$size" -le 30000 ]; then
|
||||
pass "$UI size ${size} bytes (within 1-30 KB range)"
|
||||
else
|
||||
fail "$UI size ${size} bytes (expected 1-30 KB)"
|
||||
fi
|
||||
ui_check=$(python3 << 'PYEOF'
|
||||
import re, sys
|
||||
content = open('evidence-ui/index.html').read()
|
||||
problems = []
|
||||
if '<style>' not in content or '</style>' not in content: problems.append('missing inline <style>')
|
||||
if '<script>' not in content or '</script>' not in content: problems.append('missing inline <script>')
|
||||
if 'fetch(' not in content: problems.append('missing fetch call')
|
||||
if "'./audit.json'" not in content and '"./audit.json"' not in content: problems.append('missing relative ./audit.json fetch')
|
||||
external = re.findall(r'(?:src|href)\s*=\s*["\']https?://', content)
|
||||
if external: problems.append(f'external resource refs: {external}')
|
||||
# Confirm a refresh button or refresh function exists
|
||||
if 'refresh' not in content.lower(): problems.append('no refresh button/function')
|
||||
print('OK' if not problems else 'FAIL: ' + '; '.join(problems))
|
||||
PYEOF
|
||||
)
|
||||
if [ "$ui_check" = "OK" ]; then
|
||||
pass "$UI structural checks (inline CSS/JS, fetch ./audit.json, no external refs, refresh)"
|
||||
else
|
||||
fail "$UI structural: $ui_check"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Check 2: run_demo.sh syntax ---
|
||||
echo "-- Check 2: run_demo.sh syntax + flags --"
|
||||
if bash -n scripts/run_demo.sh 2>/dev/null; then
|
||||
pass "run_demo.sh bash -n clean"
|
||||
else
|
||||
fail "run_demo.sh bash -n"
|
||||
fi
|
||||
if grep -q -- '--no-upload' scripts/run_demo.sh; then
|
||||
pass "run_demo.sh supports --no-upload flag"
|
||||
else
|
||||
fail "run_demo.sh missing --no-upload flag"
|
||||
fi
|
||||
|
||||
# --- Check 3: run_demo.sh dry-run (no upload) ---
|
||||
echo "-- Check 3: run_demo.sh --no-upload (4 acts, 11 events) --"
|
||||
rm -rf /tmp/acdl_demo_run
|
||||
out=$(ACDL_GITEA_TOKEN= bash scripts/run_demo.sh --no-upload 2>&1); rc=$?
|
||||
if [ "$rc" = "0" ]; then
|
||||
pass "run_demo.sh --no-upload exits 0"
|
||||
else
|
||||
fail "run_demo.sh --no-upload exit $rc"
|
||||
echo "$out" | tail -10
|
||||
fi
|
||||
audit="/tmp/acdl_demo_run/audit.json"
|
||||
if [ -f "$audit" ]; then
|
||||
pass "audit.json written to $audit"
|
||||
else
|
||||
fail "audit.json missing at $audit"
|
||||
fi
|
||||
|
||||
# --- Check 4: audit.json event count + Act 4 rejection ---
|
||||
echo "-- Check 4: audit.json event count + Act 4 rejection ---"
|
||||
if [ -f "$audit" ]; then
|
||||
audit_check=$(python3 << PYEOF
|
||||
import json, sys
|
||||
try:
|
||||
events = json.load(open("$audit"))
|
||||
n = len(events)
|
||||
if n < 11:
|
||||
print(f"FAIL: too few events ({n}, expected >= 11)")
|
||||
sys.exit(1)
|
||||
if not any('POLICY_VIOLATION:PUBLIC_INGRESS' in x.get('event', '') for x in events):
|
||||
print("FAIL: no Act 4 rejection event")
|
||||
sys.exit(1)
|
||||
if not any('Act 1 Friction' in x.get('event', '') for x in events):
|
||||
print("FAIL: no Act 1 event")
|
||||
sys.exit(1)
|
||||
if not any('Act 3' in x.get('event', '') for x in events):
|
||||
print("FAIL: no Act 3 event")
|
||||
sys.exit(1)
|
||||
if not any('l2-commodity-price-feed' in x.get('event', '') for x in events):
|
||||
print("FAIL: no l2-commodity-price-feed event")
|
||||
sys.exit(1)
|
||||
print(f"OK ({n} events; Act 1/2/3/4 + Act 4 rejection present)")
|
||||
except Exception as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if echo "$audit_check" | grep -q "^OK"; then
|
||||
pass "$audit_check"
|
||||
else
|
||||
fail "audit content: $audit_check"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Check 5: audit.json hash chain integrity ---
|
||||
echo "-- Check 5: audit.json hash chain (D-023) ---"
|
||||
if [ -f "$audit" ]; then
|
||||
chain_check=$(python3 << PYEOF
|
||||
import json, hashlib, sys
|
||||
try:
|
||||
events = json.load(open("$audit"))
|
||||
assert events[0]['prev_hash'] == 'GENESIS', "genesis prev_hash"
|
||||
for i in range(1, len(events)):
|
||||
assert events[i]['prev_hash'] == events[i-1]['hash'], f"chain break at {i}"
|
||||
e = dict(events[i]); h = e.pop('hash'); e['hash'] = ''
|
||||
canon = json.dumps(e, sort_keys=True, separators=(',',':'))
|
||||
assert hashlib.sha256(canon.encode()).hexdigest() == h, f"hash mismatch at {i}"
|
||||
print("OK")
|
||||
except AssertionError as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$chain_check" = "OK" ]; then
|
||||
pass "audit.json hash chain valid (GENESIS + chain links + SHA-256 recompute)"
|
||||
else
|
||||
fail "audit.json hash chain: $chain_check"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Check 6: no stray files in repo root ---
|
||||
echo "-- Check 6: no stray files in repo root ---"
|
||||
if [ -f "$ROOT/state.json" ]; then
|
||||
fail "state.json left in repo root"
|
||||
else
|
||||
pass "no state.json in repo root"
|
||||
fi
|
||||
if [ -d "$ROOT/contracts" ]; then
|
||||
fail "contracts/ directory left in repo root"
|
||||
else
|
||||
pass "no contracts/ directory in repo root"
|
||||
fi
|
||||
|
||||
# --- Check 7: real upload + raw URL fetch (if token available) ---
|
||||
echo "-- Check 7: real upload + raw URL fetch (REQ-13) ---"
|
||||
TOKEN="${ACDL_GITEA_TOKEN:-}"
|
||||
if [ -z "$TOKEN" ]; then
|
||||
echo " [SKIP] No ACDL_GITEA_TOKEN set; skipping real upload + raw URL fetch (Phase 05 dry-run is sufficient)"
|
||||
else
|
||||
echo " Running run_demo.sh (with upload)..."
|
||||
upload_out=$(bash scripts/run_demo.sh 2>&1); upload_rc=$?
|
||||
if [ "$upload_rc" = "0" ]; then
|
||||
pass "run_demo.sh (with upload) exits 0"
|
||||
else
|
||||
fail "run_demo.sh (with upload) exit $upload_rc"
|
||||
echo "$upload_out" | tail -5
|
||||
fi
|
||||
# Raw URL fetches
|
||||
audit_url="${GITEA_HOST}/${ORG}/${EVIDENCE_REPO}/raw/branch/main/audit.json"
|
||||
index_url="${GITEA_HOST}/${ORG}/${EVIDENCE_REPO}/raw/branch/main/index.html"
|
||||
audit_status=$(curl -sS -o /tmp/p05_audit_remote.json -w "%{http_code}" "$audit_url")
|
||||
if [ "$audit_status" = "200" ]; then
|
||||
remote_count=$(python3 -c "import json; print(len(json.load(open('/tmp/p05_audit_remote.json'))))" 2>/dev/null || echo "?")
|
||||
if [ "$remote_count" = "11" ] || [ "$remote_count" -ge 11 ] 2>/dev/null; then
|
||||
pass "raw audit.json returns 200 with ${remote_count} events"
|
||||
else
|
||||
pass "raw audit.json returns 200 (events: ${remote_count})"
|
||||
fi
|
||||
else
|
||||
fail "raw audit.json GET returned HTTP ${audit_status}"
|
||||
fi
|
||||
index_status=$(curl -sS -o /tmp/p05_index_remote.html -w "%{http_code}" "$index_url")
|
||||
if [ "$index_status" = "200" ]; then
|
||||
if grep -q "ACDL Evidence" /tmp/p05_index_remote.html && grep -q "audit.json" /tmp/p05_index_remote.html; then
|
||||
pass "raw index.html returns 200 with ACDL Evidence + audit.json reference"
|
||||
else
|
||||
fail "raw index.html returns 200 but missing ACDL Evidence / audit.json markers"
|
||||
fi
|
||||
else
|
||||
fail "raw index.html GET returned HTTP ${index_status}"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 05 verification PASSED (UI + 4-act dry-run, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 05 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
@@ -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