docs(P71): polish leadership decks — action headlines, trim, 6 new diagrams (v1.13)
Polish both leadership decks (how-the-platform-works + the-developer-experience) across all 4 pipeline layers (source md, marp, html, talking points). Story-arc restructure (per storytelling best practices): - Intro ~10% / Body ~80% / Conclusion ~10%; 3-5 body points per deck - One idea per slide; action headlines replace category names - Before/after 2-slide sequence (problem -> north star) on platform deck - Main 10 slides kept; detail pushed to expanded appendix (8 + 7) Word reduction + natural flow: - Remove all <em class="story"> transition lines (flow carried by headlines) - Bullets <= 12 words, 3-4 per main slide (was 5-6) - Cut parentheticals, sub-clauses, redundant restatements Design + visuals: - Larger fonts: body 22 -> 26px, h1 34 -> 40px, h2 26 -> 32px, blockquote 20 -> 24px - 6 new mermaid diagrams -> PNGs: - platform-works-02-frictions (2x2 quadrant) - platform-works-03-north-star (before/after) - platform-works-07-zero-trust (OIDC + ABAC flow) - developer-experience-05-catalog (primitives -> modules) - developer-experience-07-decommission (6-node gate flow) - developer-experience-08-semver (floating/pinned/major timeline) - At most 1 diagram per main slide; no diagrams on title/conclusion - High contrast preserved, no animations, maturity badges intact Verify: - Marp renders both decks clean (HTML re-rendered, committed) - Talking-points sections == Marp slide count per deck - No stale "deploy-unverified" claims (only closed-status disclosure) - 522 tests pass (no code touched; only docs/presentations/ files changed) - 22/22 Verified framing preserved verbatim from v1.12 ---ci--- project: acdl phase: 71 milestone: v1.13 status: complete ---/ci---
This commit is contained in:
Jon Chery
@@ -8,23 +8,22 @@ footer: "Internal"
|
||||
style: |
|
||||
section {
|
||||
font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif;
|
||||
font-size: 22px;
|
||||
font-size: 26px;
|
||||
color: #1B1B1B;
|
||||
}
|
||||
h1 { color: #D6002A; font-size: 34px; margin-bottom: 0.3em; }
|
||||
h2 { color: #D6002A; font-size: 26px; margin-bottom: 0.2em; }
|
||||
h1 { color: #D6002A; font-size: 40px; margin-bottom: 0.3em; }
|
||||
h2 { color: #D6002A; font-size: 32px; margin-bottom: 0.2em; }
|
||||
section.title { background: #1B1B1B; color: #fff; border-top: 8px solid #D6002A; }
|
||||
section.title h1 { color: #fff; }
|
||||
table { font-size: 18px; width: 100%; }
|
||||
table { font-size: 22px; width: 100%; }
|
||||
th { background: #F0F0F0; }
|
||||
blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 20px; }
|
||||
pre { font-size: 14px; line-height: 1.3; }
|
||||
code { font-size: 14px; }
|
||||
blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 24px; }
|
||||
pre { font-size: 16px; line-height: 1.3; }
|
||||
code { font-size: 16px; }
|
||||
img { display: block; margin: 0 auto; max-height: 280px; }
|
||||
em.story { color: #6B7280; font-size: 16px; font-style: italic; }
|
||||
.badge {
|
||||
display: inline-block; padding: 2px 8px; border-radius: 4px;
|
||||
font-size: 14px; font-weight: 600;
|
||||
font-size: 16px; font-weight: 600;
|
||||
}
|
||||
.testing { background: #DBEAFE; color: #1E3A5F; }
|
||||
.planned { background: #fef3c7; color: #78350f; }
|
||||
@@ -45,24 +44,18 @@ section.title h3 { color: #F0F0F0; font-weight: 400; font-size: 22px; margin-top
|
||||
|
||||
---
|
||||
|
||||
# Where Agentic Cloud Delivery (ACDL) Sits in Your World
|
||||
|
||||
<em class="story">Here's who uses the platform and where the boundary is.</em>
|
||||
# Two consumer paths, one safety envelope
|
||||
|
||||
|
||||
|
||||
- **Technical developer** — owns app code + a contract + a thin CI definition
|
||||
- **Citizen developer** — declares intent in plain language; an AI agent produces a contract that passes the **same** safety envelope <span class="badge agentic">Agentic</span>
|
||||
- **Upstream is anything** — your IDE, an agentic SDLC, or vibe coding on a laptop. ACDL doesn't care how the contract was produced
|
||||
- **ACDL is infrastructure only** — it provisions and governs AWS resources. Application deployment is upstream
|
||||
- **Citizen developer** — declares intent; an AI agent produces a contract that passes the **same** safety envelope <span class="badge agentic">Agentic</span>
|
||||
- **Upstream is anything** — IDE, agentic SDLC, or vibe coding. ACDL doesn't care how the contract was produced
|
||||
- **ACDL is infrastructure only** — provisions and governs AWS resources. Application deployment is upstream
|
||||
|
||||
---
|
||||
|
||||
# The Contract — The Entire Consumer Surface
|
||||
|
||||
<em class="story">Now let's look at what a consumer actually writes — it's tiny.</em>
|
||||
|
||||
Three things. That is the entire consumer-side surface.
|
||||
# Three things. The entire consumer surface.
|
||||
|
||||
<img src="assets/png/developer-experience-02-what-dev-does.png" style="float: right; width: 38%; margin-left: 20px; margin-bottom: 10px;" />
|
||||
|
||||
@@ -84,42 +77,84 @@ infrastructure:
|
||||
```
|
||||
|
||||
- **3. A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
|
||||
- The developer does **not**: write infrastructure modules, clone the platform repo, hold cloud credentials, or maintain a state backend
|
||||
- The developer does **not**: write modules, clone the platform repo, hold cloud credentials, or maintain a state backend
|
||||
|
||||
---
|
||||
|
||||
# The Developer Feedback Loop
|
||||
# See what the platform does, in real time
|
||||
|
||||
<em class="story">Once you push, here's what you see — in real time, in your own logs.</em>
|
||||
|
||||
Developers see **what the platform is doing**, in real time. <span class="badge testing">Testing</span>
|
||||
|
||||
- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record flow to stdout
|
||||
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard
|
||||
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque debugging exercise.**
|
||||
- **Connection strings posted as PR comments** — human-readable, no hunting
|
||||
- **Runtime secrets in encrypted Parameter Store** — KMS-encrypted, namespaced, **no raw secrets in logs**
|
||||
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo
|
||||
- **Streamed output by default** — the plan, policy results, and each check record flow to stdout
|
||||
- **PR comments after every successful pipeline stage** — always know where you stand
|
||||
- **Clear, explainable halt reasons** — a policy violation, an insufficient signal, or a missing attestation. **Never opaque.**
|
||||
- **Connection strings posted as PR comments** — human-readable, no hunting. Runtime secrets go to encrypted Parameter Store, never to logs
|
||||
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo <span class="badge testing">Testing</span>
|
||||
|
||||
---
|
||||
|
||||
# Versioned, Predictable Releases
|
||||
# Pick from pre-built, security-reviewed blocks
|
||||
|
||||
<em class="story">You control when you absorb platform improvements — no surprise upgrades.</em>
|
||||
|
||||
|
||||
Consumers control **when** they absorb platform improvements. <span class="badge testing">Testing</span>
|
||||
- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, ALB, ECR, CloudFront, WAF, RDS)
|
||||
- **Modules** — composed patterns (static site with CDN + WAF; microservice with VPC + ECS + ALB + ECR)
|
||||
- **Validated examples per module** — `simple.yaml` + `complex.yaml`, validated against the contract schema in CI
|
||||
- **Auto-promotion of patterns** — after 3 observed usages <span class="badge planned">Planned</span> <span class="badge agentic">Agentic</span>
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.12`) — a consumer automatically receives patch updates within the line
|
||||
---
|
||||
|
||||
# The bar rises automatically with sensitivity
|
||||
|
||||
|
||||
|
||||
| Environment | What the platform adds | Maturity |
|
||||
|---|---|---|
|
||||
| dev | Confidence ≥ 0.50, fully autonomous | <span class="badge testing">Testing</span> |
|
||||
| qa | QA human attestation + confidence ≥ 0.75 | <span class="badge planned">Planned</span> |
|
||||
| prod | SRE human attestation + confidence ≥ 0.90 | <span class="badge planned">Planned</span> |
|
||||
| dr | SRE human attestation + confidence ≥ 0.95 + DR drill | <span class="badge planned">Planned</span> |
|
||||
|
||||
- **No staging environment** — dev is the only autonomous environment
|
||||
- **Separation of duties** — the QA approver cannot be the prod approver
|
||||
|
||||
---
|
||||
|
||||
# Tearing down is as gated as deploying
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
section { font-size: 22px; }
|
||||
pre { font-size: 13px; line-height: 1.2; }
|
||||
code { font-size: 13px; }
|
||||
</style>
|
||||
|
||||
```yaml
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.12
|
||||
with:
|
||||
contract: .acdl/contract.yml
|
||||
mode: decommission
|
||||
changeRequestId: "CHG0678912"
|
||||
```
|
||||
|
||||
- **Validate the change request** — platform queries the CMDB; CR must be `approved` and match the consumer repo
|
||||
- **Two SRE human-attestation gates** — disable protection → SRE approves → zero counts + destroy → second SRE approves
|
||||
- **Per-stack encryption key enters a grace window** (default 30 days) so encrypted data remains recoverable <span class="badge testing">Testing</span>
|
||||
|
||||
---
|
||||
|
||||
# You control when you absorb improvements
|
||||
|
||||
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.12`) — automatically receive 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
|
||||
- **Pin to an exact version** for stability, or float on MAJOR only (`@v1`) to absorb new features on your own cadence
|
||||
- **Unversioned references (`@main`, bare) are discouraged** — the versioned tag is the only immutability lever
|
||||
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags
|
||||
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates floating tags <span class="badge testing">Testing</span>
|
||||
|
||||
---
|
||||
|
||||
# Friendly Onboarding
|
||||
|
||||
<em class="story">First impressions matter — the platform fails gracefully, not opaquely.</em>
|
||||
# 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>
|
||||
|
||||
@@ -136,111 +171,18 @@ The pipeline then **exits without attempting a deployment** — no partial state
|
||||
|
||||
---
|
||||
|
||||
# Safe Promotion Path
|
||||
|
||||
<em class="story">Promotion is a workflow choice, not a contract edit — and the bar rises automatically.</em>
|
||||
|
||||
The contract is environment-agnostic. The platform raises the bar automatically.
|
||||
|
||||
|
||||
|
||||
<table style="width: 100%; border: none;">
|
||||
<tr>
|
||||
<td style="width: 50%; vertical-align: top; border: none; padding-right: 12px;">
|
||||
|
||||
**Approach A — One contract, one job per environment.** Environment passed by each job.
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.12
|
||||
with: { contract: .acdl/contract.yml, environment: dev }
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.12
|
||||
with: { contract: .acdl/contract.yml, environment: qa }
|
||||
```
|
||||
|
||||
</td>
|
||||
<td style="width: 50%; vertical-align: top; border: none; padding-left: 12px;">
|
||||
|
||||
**Approach B — Environment-specific contracts.** When inputs differ per environment.
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
dev:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.12
|
||||
with: { contract: .acdl/contract-dev.yaml }
|
||||
qa:
|
||||
needs: dev
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.12
|
||||
with: { contract: .acdl/contract-qa.yaml }
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<style>
|
||||
section { font-size: 16px; }
|
||||
pre { font-size: 10px; line-height: 1.2; }
|
||||
code { font-size: 10px; }
|
||||
td { font-size: 14px; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# Safe Decommission
|
||||
|
||||
<em class="story">Tearing down is as deliberate as deploying — and just as gated.</em>
|
||||
|
||||
Tearing down a stack is **as deliberate as deploying one.** <span class="badge testing">Testing</span>
|
||||
|
||||
```yaml
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.12
|
||||
with:
|
||||
contract: .acdl/contract.yml
|
||||
mode: decommission
|
||||
changeRequestId: "CHG0678912"
|
||||
```
|
||||
|
||||
A 2-step pipeline with **two SRE human-attestation gates**:
|
||||
|
||||
1. **Validate the change request** — the platform queries the CMDB; the CR must be `approved` and match the consumer repo
|
||||
2. **Disable deletion protection** → **SRE approves** → **Zero all counts + destroy** → **a second SRE approves**
|
||||
|
||||
The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable.
|
||||
|
||||
---
|
||||
|
||||
# Self-Service Module Catalog
|
||||
|
||||
<em class="story">You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.</em>
|
||||
|
||||
Developers pick from **pre-built, security-reviewed building blocks.** <span class="badge testing">Testing</span>
|
||||
|
||||
- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, load balancer, container registry, CloudFront, WAF, RDS), each with documented inputs/outputs, usage, compliance extension points, and versioning
|
||||
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry)
|
||||
- **Validated examples per module** — `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently
|
||||
- **Auto-promotion of patterns** — auto-promoted to the catalog after 3 observed usages <span class="badge planned">Planned</span> <span class="badge agentic">Agentic</span>
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, DORA controls will wire in <span class="badge planned">Planned</span>
|
||||
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# The Desired Outcomes
|
||||
# The desired outcomes
|
||||
|
||||
<em class="story">Here's what this delivers to the organization.</em>
|
||||
|
||||
- **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.
|
||||
- **Auditability as a byproduct, not a project.** Every production change is traceable to a human attestation and a tamper-evident evidence event.
|
||||
- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources.
|
||||
- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread.
|
||||
- **Infrastructure as a utility, not a craft.** Teams consume infrastructure, they don't maintain it — and the platform compounds value over time by learning from recurring patterns.
|
||||
- **A path to the citizen developer.** The same safety envelope that serves a senior engineer will serve a non-technical consumer. <span class="badge agentic">Agentic</span>
|
||||
- **Velocity without sacrificing safety** — speed in ergonomics, safety in unbypassable gates
|
||||
- **Security, observability, compliance as platform defaults** — not per-team effort, not post-hoc remediation
|
||||
- **Auditability as a byproduct, not a project** — every change traceable to a human attestation and a tamper-evident evidence event
|
||||
- **Blast radius contained by design** — OIDC + ABAC, only your own tagged resources
|
||||
- **The bottleneck moves off the platform team's ticket queue** — a merged change progresses without a platform engineer joining a thread
|
||||
- **Infrastructure as a utility, not a craft** — consume, don't maintain
|
||||
- **A path to the citizen developer** — same envelope, senior engineer or non-technical <span class="badge agentic">Agentic</span>
|
||||
|
||||
---
|
||||
|
||||
@@ -249,8 +191,6 @@ Developers pick from **pre-built, security-reviewed building blocks.** <span cla
|
||||
|
||||
# Appendix
|
||||
|
||||
<em class="story">For deep dives — these slides cover details omitted from the main 10.</em>
|
||||
|
||||
**Contents:**
|
||||
|
||||
1. The Citizen Developer Experience (full)
|
||||
@@ -328,15 +268,14 @@ The entire CI pipeline runs **from the shell**, not just in CI. <span class="bad
|
||||
| **HITL** | Human-in-the-Loop — deliberate human attestation required for qa/prod/dr environments |
|
||||
| **VCS** | Version Control System — the git hosting platform (GitHub, Gitea, GitLab) |
|
||||
| **NFR** | Non-Functional Requirement — encryption, tagging, observability standards |
|
||||
| **IR** | Intermediate Representation — the engine-agnostic stack definition between contract and Terraform |
|
||||
|
||||
---
|
||||
|
||||
# A6 — Operating Model & Cost
|
||||
|
||||
<style>
|
||||
section { font-size: 18px; }
|
||||
table { font-size: 16px; }
|
||||
section { font-size: 20px; }
|
||||
table { font-size: 18px; }
|
||||
</style>
|
||||
|
||||
ACDL runs at **zero cloud cost** for day-to-day development. AWS spend was measured via Cost Explorer (`COST.md`, 2026-07-28):
|
||||
@@ -348,12 +287,11 @@ ACDL runs at **zero cloud cost** for day-to-day development. AWS spend was measu
|
||||
| Projected monthly | ~$0.007 |
|
||||
| Peak day | 2026-07-27 ($0.000867) |
|
||||
|
||||
- **S3 dominates** (98.8%, terraform state bucket) — no compute (ECS/Lambda) ran because v1.0→v1.10 was plan-only for IAM-gated capabilities
|
||||
- **Local emulators are the primary tier** — the full pipeline runs in-process, no AWS credentials, no Checkov, no DynamoDB. <span class="badge testing">Testing</span>
|
||||
- **Live-AWS verification is milestone-scoped, then torn down.** The v1.11 lifecycle pipeline ran apply→modify→destroy for every module, then tore down to zero-cost (D-096). The pipeline now **defaults to plan-only** on every PR; `ACDL_LIFECYCLE_MODE=full` overrides to apply→destroy for milestone verification (REQ-134, v1.12).
|
||||
- **Local emulators are the primary tier** — the full pipeline runs in-process, no AWS credentials <span class="badge testing">Testing</span>
|
||||
- **Live-AWS verification is milestone-scoped, then torn down.** The pipeline now **defaults to plan-only** on every PR; `ACDL_LIFECYCLE_MODE=full` overrides to apply→destroy for milestone verification (REQ-134, v1.12).
|
||||
- **Cost drivers** are spike-scoped: Terraform plan reads (free), S3 state storage (cents), DynamoDB outbox (cents). No running infrastructure between milestones.
|
||||
|
||||
**Pre-mortem (`PRE_MORTEM.md`):** failure modes were pre-mortemed before the leadership pitch. The v1.10 decay incident (diff-scoped VERIFY missed 7 adapter defects) is the root pattern: *a claim outruns the verification that backs it.* Four forward failure modes + structural mitigations (regression-tested IAM baseline, mandatory teardown, verified-only deck claims, honest scope).
|
||||
**Pre-mortem (`PRE_MORTEM.md`):** the v1.10 decay incident (diff-scoped VERIFY missed 7 adapter defects) is the root pattern: *a claim outruns the verification that backs it.* Four forward failure modes + structural mitigations (regression-tested IAM baseline, mandatory teardown, verified-only deck claims, honest scope).
|
||||
|
||||
---
|
||||
|
||||
@@ -362,13 +300,11 @@ ACDL runs at **zero cloud cost** for day-to-day development. AWS spend was measu
|
||||
|
||||
# A7 — Verified by Construction
|
||||
|
||||
<em class="story">The v1.11 architecture makes "Verified" a structural property, not a claim.</em>
|
||||
|
||||
<style>
|
||||
section { font-size: 18px; }
|
||||
section { font-size: 20px; }
|
||||
</style>
|
||||
|
||||
Two architectural pillars:
|
||||
Two architectural pillars make "Verified" a structural property, not a claim:
|
||||
|
||||
- **The stateless adapter (918 → ~80 lines).** The Terraform adapter was a 918-line monolith with 3 constant tables and 39 type-specific branches. It is now a ~80-line **stateless assembler**: it owns no module content — no resource shape, no nested HCL blocks, no defaults. Each L1 module ships a real `terraform/` module dir owning its shape, nested blocks, and defaults. The adapter reads the registry and emits `module "x" { source = ... }` blocks. A new module is a new terraform dir, not a code change. *(The v1.12 P67 fix closed a dedup defect for multi-resource L1s — ecs-service, alb; CAP-013 now Verified.)*
|
||||
- **Pipeline-driven lifecycle testing.** A `modules-lifecycle` pipeline matrix-runs each L1 and L2 module's contracts through apply→modify→destroy against live AWS. **The "test" = the pipeline cell going green.** Defaults to **plan-only** on every PR (fast, no AWS mutation, no cost); `ACDL_LIFECYCLE_MODE=full` overrides to the real apply→destroy for milestone verification (REQ-134, v1.12). The regression gate (D-091) re-runs all 22 capabilities at milestone completion — **22/22 Verified** as of v1.12.
|
||||
|
||||
Reference in New Issue
Block a user