docs(P57): polish PW & DX decks — new contract shape, S&P mermaid theme, Verification Coverage, Operating Model appendix
Contract examples updated to new shape:
- DX Slide 3 contract example: id/name/environment/infrastructure (no uses:, no module:)
- Version pins bumped from @v1.6/@v1.8 to @v1.10
- .acdl/contract.yaml → .acdl/contract.yml in all deck examples
Story beat prefix stripped:
- All 'Story beat: ' prefixes removed from narrative lines (DX source + both Marp decks)
- PW source-of-truth: added narrative lines to fix P51 drift (PW Marp had them, PW source didn't)
DX Slide 2 reconciliation:
- Title: 'Where ACDL Sits' → 'Where Agentic Cloud Delivery (ACDL) Sits' (spelled out)
- Source-of-truth inline mermaid reconciled to match .mmd/PNG (subgraphed LR version)
- Prose: added ACDL definition line
S&P mermaid theme (all 10 diagrams):
- assets/mmd/sp-theme.json: canonical S&P Red/Black/White theme
- Each .mmd file: %%{init:...}%% block with inline theme (self-contained)
- Two-tone classDef: accent (dark fill, white text, red border) for key nodes,
supporting (white fill, black text, red border) for the rest
- All 10 PNGs re-rendered with --configFile sp-theme.json
- README build command updated with --configFile flag
GRILL G-005 (Verification Coverage):
- PW Slide 9: added block listing 6 deploy-unverified capabilities (CAP-017..022)
- DX A6: same block included in the new appendix slide
GRILL G-008 (Operating Model & Cost):
- Both decks: new A6 appendix slide (local emulators primary tier, zero cloud cost,
live-AWS one-off spike per milestone, no BAU spend)
Cross-deck consistency:
- DX glossary: added missing IR row (PW had it, DX didn't)
- Both decks: 7-appendix convention (TOC updated, A1-A6)
HTML re-rendered:
- Both decks re-rendered from updated Marp source
---ci---
project: acdl
phase: 57
milestone: v1.10.2
status: execute
---/ci---
This commit is contained in:
Jon Chery
@@ -17,21 +17,36 @@ The consumer surface is intentionally tiny. The platform's surface is large and
|
||||
|
||||
---
|
||||
|
||||
## Slide 2 — Where ACDL Sits in Your World
|
||||
## Slide 2 — Where Agentic Cloud Delivery (ACDL) Sits in Your World
|
||||
|
||||
Story beat: Here's who uses the platform and where the boundary is.
|
||||
Here's who uses the platform and where the boundary is.
|
||||
|
||||
The platform serves **two kinds of consumer** through two coordinated paths — but both converge on the **same contract, the same policy envelope, and the same evidence stream.**
|
||||
|
||||
**Agentic Cloud Delivery (ACDL)** sits between upstream (anything that produces a contract) and downstream (AWS resources running + the consumer's image pipeline).
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
U1["Anything upstream<br/>(IDE / agentic SDLC / vibe coding)"] --> T["Technical developer<br/>writes app + contract"]
|
||||
U1 --> C["Citizen developer<br/>declares intent"]
|
||||
T --> K["Contract YAML"]
|
||||
C --> AI["An AI agent maps intent<br/>to a reviewed-skill contract"]
|
||||
AI --> K
|
||||
K --> ACDL["ACDL — infrastructure only<br/>resolve → check → plan → policy<br/>→ confidence → evidence → apply"]
|
||||
ACDL --> AWS["AWS resources provisioned + governed"]
|
||||
flowchart LR
|
||||
subgraph UP ["Upstream — anything"]
|
||||
direction TB
|
||||
A["Technical dev\n(app code + contract)"]
|
||||
B["Citizen dev\n(intent → AI agent\n→ contract)"]
|
||||
end
|
||||
subgraph ACDL ["ACDL — infrastructure only"]
|
||||
C["Same contract\nSame pipeline\nSame safety"]
|
||||
D["Provision\nAWS resources"]
|
||||
E["Evidence\nhash-chained"]
|
||||
end
|
||||
subgraph DOWN ["Downstream"]
|
||||
F["AWS resources\nrunning"]
|
||||
G["Consumer pipeline\ndeploys image"]
|
||||
end
|
||||
A --> C
|
||||
B --> C
|
||||
C --> D
|
||||
C --> E
|
||||
D --> F
|
||||
F --> G
|
||||
```
|
||||
|
||||
- **Technical developer** — owns app code + a contract + a thin CI definition. Uses the full module catalog and inputs.
|
||||
@@ -47,23 +62,26 @@ The platform is **opinionated in what it accepts, regardless of who is declaring
|
||||
|
||||
## Slide 3 — The Contract — The Entire Consumer Surface
|
||||
|
||||
Story beat: Now let's look at what a consumer actually writes — it's tiny.
|
||||
Now let's look at what a consumer actually writes — it's tiny.
|
||||
|
||||
Three things. That is the entire consumer-side surface.
|
||||
|
||||
1. **App code** — the consumer's service, at the top level of the repo
|
||||
2. **A contract** — a single YAML file: module, environment, inputs
|
||||
2. **A contract** — a single YAML file: id, name, environment, infrastructure
|
||||
3. **A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
module: microservice
|
||||
id: msvc
|
||||
name: microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
cpu: 256
|
||||
memory: 512
|
||||
desired_count: 2
|
||||
port: 8080
|
||||
infrastructure:
|
||||
microservice:
|
||||
version: "1.0.0"
|
||||
inputs:
|
||||
cpu: 256
|
||||
memory: 512
|
||||
desired_count: 2
|
||||
port: 8080
|
||||
```
|
||||
|
||||
The developer does **not**:
|
||||
@@ -80,7 +98,7 @@ The developer does **not**:
|
||||
|
||||
## Slide 4 — The Developer Feedback Loop
|
||||
|
||||
Story beat: Once you push, here's what you see — in real time, in your own logs.
|
||||
Once you push, here's what you see — in real time, in your own logs.
|
||||
|
||||
Developers see **what the platform is doing**, in real time. <span class="badge testing">Testing</span>
|
||||
|
||||
@@ -96,11 +114,11 @@ Developers see **what the platform is doing**, in real time. <span class="badge
|
||||
|
||||
## Slide 5 — Versioned, Predictable Releases
|
||||
|
||||
Story beat: You control when you absorb platform improvements — no surprise upgrades.
|
||||
You control when you absorb platform improvements — no surprise upgrades.
|
||||
|
||||
Consumers control **when** they absorb platform improvements. <span class="badge testing">Testing</span>
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line.
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.10`) — a consumer automatically receives patch updates within the line.
|
||||
- **Semantic versioning with a clear contract:** interface → MAJOR, behavior → MINOR, lifecycle → PATCH.
|
||||
- **A consumer can pin to an exact version** for maximum stability, or float on MAJOR only (`@v1`) to absorb new features on their own cadence.
|
||||
- **Unversioned references (`@main`, bare) are discouraged** — the versioned tag is the only immutability lever a consumer has.
|
||||
@@ -112,7 +130,7 @@ Consumers control **when** they absorb platform improvements. <span class="badge
|
||||
|
||||
## Slide 6 — Friendly Onboarding
|
||||
|
||||
Story beat: First impressions matter — the platform fails gracefully, not opaquely.
|
||||
First impressions matter — the platform fails gracefully, not opaquely.
|
||||
|
||||
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. <span class="badge testing">Testing</span>
|
||||
|
||||
@@ -133,7 +151,7 @@ The pipeline then **exits without attempting a deployment** — no partial state
|
||||
|
||||
## Slide 7 — Safe Promotion Path
|
||||
|
||||
Story beat: Promotion is a workflow choice, not a contract edit — and the bar rises automatically.
|
||||
Promotion is a workflow choice, not a contract edit — and the bar rises automatically.
|
||||
|
||||
The contract is environment-agnostic. The platform raises the bar automatically.
|
||||
|
||||
@@ -149,12 +167,12 @@ flowchart LR
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with: { contract: .acdl/contract.yaml, environment: dev }
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.10
|
||||
with: { contract: .acdl/contract.yml, environment: dev }
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
with: { contract: .acdl/contract.yaml, environment: qa }
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.10
|
||||
with: { contract: .acdl/contract.yml, environment: qa }
|
||||
```
|
||||
|
||||
**Approach B — Environment-specific contracts.** When inputs genuinely differ per environment, each job points at its own contract file. The pipeline, policy, and confidence model stay identical.
|
||||
@@ -162,11 +180,11 @@ jobs:
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.10
|
||||
with: { contract: .acdl/contract-dev.yaml }
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.6
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.10
|
||||
with: { contract: .acdl/contract-qa.yaml }
|
||||
```
|
||||
|
||||
@@ -189,14 +207,14 @@ Whichever approach a team picks, the platform applies the same rising bar:
|
||||
|
||||
## Slide 8 — Safe Decommission
|
||||
|
||||
Story beat: Tearing down is as deliberate as deploying — and just as gated.
|
||||
Tearing down is as deliberate as deploying — and just as gated.
|
||||
|
||||
Tearing down a stack is **as deliberate as deploying one.** <span class="badge testing">Testing</span>
|
||||
|
||||
```yaml
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.8
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.10
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
contract: .acdl/contract.yml
|
||||
mode: decommission
|
||||
changeRequestId: "CHG0678912"
|
||||
```
|
||||
@@ -214,7 +232,7 @@ The per-stack encryption key enters a **grace window** (default 30 days) so encr
|
||||
|
||||
## Slide 9 — Self-Service Module Catalog
|
||||
|
||||
Story beat: You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.
|
||||
You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.
|
||||
|
||||
Developers pick from **pre-built, security-reviewed building blocks.** <span class="badge testing">Testing</span>
|
||||
|
||||
@@ -230,7 +248,7 @@ Developers pick from **pre-built, security-reviewed building blocks.** <span cla
|
||||
|
||||
## Slide 10 — The Desired Outcomes
|
||||
|
||||
Story beat: Here's what this delivers to the organization.
|
||||
Here's what this delivers to the organization.
|
||||
|
||||
- **Velocity without sacrificing safety.** Speed is in the ergonomics (a simple contract, a one-line `uses:`); safety is in the gates the consumer cannot bypass.
|
||||
- **Security, observability, and compliance as platform defaults** — not per-team effort, not post-hoc remediation. Encryption, deletion protection, uptime monitoring, policy checks, and evidence are on by construction.
|
||||
|
||||
Reference in New Issue
Block a user