Jon Chery
eb7634da28
v1.15-Nova rebrand doc verification (phase/05-final-review-ship) found stale ACDL references where the code/terraform already uses Nova names. Critical drift fixed (doc said old name; code uses new): - README.md: `.acdl/contract.yml` -> `.nova/contract.yml`; `acdl-spike-runner` -> `nova-spike-runner`; ABAC tag keys `acdl:owner|contract` -> `nova:owner|contract`. - docs/environments/index.md: `acdl-contract-ingestor` -> `nova-contract-ingestor`; `aws:PrincipalTag/acdl:owner` -> `nova:owner`; `acdl-contracts` -> `nova-contracts`. - docs/consumer-guide.md: `acdl-change-requests` -> `nova-change-requests`; state bucket example `acdl-qa-state` -> `nova-qa-state`. - docs/presentations/* (4 decks + 2 HTML + talking-points): `acdl:owner|contract| environment|cost-center` -> `nova:*`; `ACDL_LIFECYCLE_MODE` -> `NOVA_LIFECYCLE_MODE`. - pipelines/modules-lifecycle.yml comments: `ACDL_LIFECYCLE_MODE` -> `NOVA_LIFECYCLE_MODE` (workflows already use NOVA_; the contract comments were stale). - docs/NOVA_MIGRATION.md: status banner -> COMPLETE (P5 cutoff passed). - .ciagent/ARCHITECTURE.md: header `ACDL` -> `Nova`; NOVA_LIFECYCLE_MODE rename noted in the live lifecycle-mode section (v1.15 addendum already correct). - .ciagent/ROADMAP.md: v1.15 phase statuses P1-P4 pending -> complete (v1.15.1..v1.15.4); P5 -> in progress (phase/05-final-review-ship). Verification: - grep for `acdl:*` tag keys / `.acdl/contract` / `acdl-contract-ingestor` / `acdl-contracts` / `ACDL_LIFECYCLE_MODE` in README/docs/pipelines -> 0 hits (excluding explicitly-unchanged repo path `acdl/.github/...`, `continuous-intelligence/acdl`, and historical narrative). - core/output_publisher.py uses `/nova`; schemas/tagging-standard.json uses `nova:*`; terraform uses `nova-*` (0 `acdl-` in *.tf) — docs now match. - git tag v1.15.0..v1.15.4 exist. - pytest tests/test_lifecycle_mode_flag.py tests/test_pipeline_contract.py -> 111 passed. ---ci--- project: acdl
334 lines
14 KiB
Markdown
334 lines
14 KiB
Markdown
---
|
|
marp: true
|
|
theme: default
|
|
paginate: true
|
|
size: 16x9
|
|
header: "How The Platform Works"
|
|
footer: "Internal"
|
|
style: |
|
|
section {
|
|
font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif;
|
|
font-size: 26px;
|
|
color: #1B1B1B;
|
|
}
|
|
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: 22px; width: 100%; }
|
|
th { background: #F0F0F0; }
|
|
blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 24px; }
|
|
img { display: block; margin: 0 auto; max-height: 300px; }
|
|
.badge {
|
|
display: inline-block; padding: 2px 8px; border-radius: 4px;
|
|
font-size: 16px; font-weight: 600;
|
|
}
|
|
.planned { background: #fef3c7; color: #78350f; }
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# How The Platform Works
|
|
|
|
### Nova — The New Dawn of DevSecOps
|
|
|
|
<style>
|
|
section.title h1 { font-size: 44px; margin-bottom: 0.1em; }
|
|
section.title h3 { color: #F0F0F0; font-weight: 400; font-size: 22px; margin-top: 0; }
|
|
</style>
|
|
|
|
---
|
|
|
|
# Four frictions slow every team
|
|
|
|
|
|
|
|
- **Cognitive load** — services inconsistent in security and observability
|
|
- **Operational work** — manual promotion scaling with the system
|
|
- **Red tape** — tickets and handoffs scaling with the organization
|
|
- **Scalability** — throughput without scaling platform engineers
|
|
|
|
---
|
|
|
|
# The platform at a glance
|
|
|
|
|
|
|
|
- **Consumer surfaces** — technical dev or citizen dev; both produce a contract
|
|
- **Central pipeline** — fixed stages, identical for every deployment: validate → resolve → security → plan → policy → confidence → evidence → apply
|
|
- **Module catalog + engine adapter** — security-reviewed blocks; the adapter is the only engine-specific code (Terraform today)
|
|
- **HITL gates + evidence stream** — human attestation for qa/prod/dr; every deployment writes a hash-chained event (RPO = 0)
|
|
|
|
---
|
|
|
|
# Declare intent; the platform delivers safe production
|
|
|
|
|
|
|
|
- A merged change progresses **without a ticket or thread**
|
|
- A **non-technical consumer** ships by declaring intent
|
|
- Every production change is **traceable to a human attestation**
|
|
|
|
---
|
|
|
|
# Nova owns infrastructure, not your app
|
|
|
|
|
|
|
|
- **Upstream is anything** — IDE, agentic SDLC, or vibe coding
|
|
- **Nova is infrastructure only** — provisions and governs AWS resources
|
|
- **Not a general-purpose AI** — autonomy is narrow, policy-bounded
|
|
- **Not a permissive highway** — no escape hatches
|
|
|
|
---
|
|
|
|
# One YAML file. The platform owns everything else.
|
|
|
|
|
|
|
|
- **Module** — pre-built, security-reviewed building blocks
|
|
- **Environment** — `dev`, `qa`, `prod`, `dr`; bar rises with sensitivity
|
|
- **Inputs** — cpu, memory, port, desired_count
|
|
- Consumer provides **no AWS account, no VPC, no state backend**
|
|
|
|
---
|
|
|
|
# Same stages, same checks, every deployment
|
|
|
|
|
|
|
|
- **Security and policy checks run *before* any infra is created**
|
|
- **Every stage produces a record** — no "unchecked" path
|
|
|
|
---
|
|
|
|
# No long-lived credentials. Blast radius contained.
|
|
|
|
|
|
|
|
- **OIDC federation** — short-lived token per job, no stored credential <span class="badge planned">Planned: all runners</span>
|
|
- **ABAC, not role-based** — repo identity + resource tags scope every action
|
|
- **A consumer can only touch its own tagged resources.** One consumer can never affect another.
|
|
|
|
---
|
|
|
|
# Safety is a measurable signal, not a black box
|
|
|
|
|
|
|
|
- **Six weighted inputs** — manually tuned, auditable per-input breakdown
|
|
|
|
| Environment | Threshold | Attester |
|
|
|---|---|---|
|
|
| dev | ≥ 0.50 | No one — autonomous |
|
|
| qa | ≥ 0.75 | QA <span class="badge planned">Planned</span> |
|
|
| prod | ≥ 0.90 | SRE <span class="badge planned">Planned</span> |
|
|
|
|
- **A single critical finding hard-blocks** — not averaged away
|
|
|
|
---
|
|
|
|
# Every change traceable to a human attestation
|
|
|
|
|
|
|
|
- **Dev is fully autonomous** — confidence signal is the only gate
|
|
- **qa, prod, dr require human attestation** — contract + plan + evidence <span class="badge planned">Planned</span>
|
|
- **Separation of duties** — QA approver ≠ prod approver; platform **blocks on a match** <span class="badge planned">Planned</span>
|
|
- **Hash-chained evidence event** — tampering breaks the chain. **RPO = 0**
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# The vision realized
|
|
|
|
- **Velocity without sacrificing safety** — speed in ergonomics, safety in unbypassable gates
|
|
- **Security, observability, compliance as platform defaults** — not per-team effort
|
|
- **Auditability as a byproduct, not a project** — every change traceable to a human attestation
|
|
- **Blast radius contained by design** — OIDC + ABAC, only your own tagged resources
|
|
- **Infrastructure as a utility, not a craft** — consume, don't maintain
|
|
- **A path to the citizen developer** — same envelope, senior engineer or non-technical
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# Appendix
|
|
|
|
**Contents:**
|
|
|
|
1. Platform-Managed Environments (detail)
|
|
2. Observability Built In (detail)
|
|
3. Security by Construction (the full defaults inventory)
|
|
4. The Road to the North Star (phased roadmap)
|
|
5. Testing vs. Planned (full inventory)
|
|
6. Glossary
|
|
7. Operating Model & Cost (real AWS spend + pre-mortem)
|
|
8. Verified by Construction (the v1.11 architecture)
|
|
|
|
---
|
|
|
|
# A1 — Platform-Managed Environments
|
|
|
|
A consumer provides **no AWS account, no VPC, no subnet, no state backend, no runner key.** The platform owns the blast radius.
|
|
|
|
A named environment is a platform-owned bundle of:
|
|
|
|
- An AWS account (or a scoped partition of one)
|
|
- A network (VPC + subnets)
|
|
- A state backend (S3 + DynamoDB for state + locking)
|
|
- An IAM role surfaced via ABAC, scoped to the consumer's identity and resource tags
|
|
|
|
The consumer selects an environment **by name** in their contract. The platform resolves it at run time. **The consumer never sees raw credentials.**
|
|
|
|
**Friendly onboarding:** the first run detects no environment and emits a guided prompt (not an opaque failure). <span class="badge planned">Self-service: planned</span>
|
|
|
|
---
|
|
|
|
# A2 — Observability Built In
|
|
|
|
Monitoring is **a platform default, not a per-team project.**
|
|
|
|
- **Uptime monitoring deployed automatically with every stack** — separate state, feature flag to disable
|
|
- **Monitored endpoints passed from the deployment's own outputs** — no manual endpoint registration
|
|
- **Alert channels:** Microsoft Teams webhook, email, SMS, and GitHub issues
|
|
- **The uptime URL is published to the developer** via a PR comment
|
|
- **Roadmap:** deeper observability bootstrap (dashboards, runbooks, on-call bindings) <span class="badge planned">Planned</span>
|
|
|
|
---
|
|
|
|
# A3 — Security by Construction
|
|
|
|
Security defaults that **do not require a team to opt in.** Checks run on **every** deployment, normalized to a single schema.
|
|
|
|
- **Policy checks** (Checkov, Wiz, Kyverno) — secrets, public ingress, IAM wildcards, **required tagging** — all run *before* infra is created
|
|
- **Encryption on every resource** — at-rest on by default; per-stack CMKs with 90-day rotation, **no shared keys across stacks**
|
|
- **Deletion protection on by default** — `prevent_destroy` on unless explicitly disabled via a documented flag
|
|
- **Safe decommission** — a 2-step pipeline with **two SRE attestation gates** and a **change-request validated against the CMDB**
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# A4 — The Road to the North Star
|
|
|
|
*Proposed phasing — not formally planned.*
|
|
|
|
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# A5 — Testing vs. Planned (Full Inventory)
|
|
|
|
<style>
|
|
section { font-size: 18px; }
|
|
td { font-size: 16px; vertical-align: top; }
|
|
ul { margin: 0; padding-left: 1.2em; }
|
|
li { margin-bottom: 2px; }
|
|
</style>
|
|
|
|
**22/22 Verified** — the v1.11 lifecycle pipeline ran apply→modify→destroy against live AWS for every L1 + L2 module, then tore down to zero-cost (D-096). The v1.10 "6 deploy-unverified (IAM drift)" status is closed (CAP-013 fixed in P67).
|
|
|
|
<table style="width: 100%; border: none;">
|
|
<tr>
|
|
<td style="width: 52%; border: none; padding-right: 12px;">
|
|
|
|
**Testing** (22/22 Verified — works internally, dev pilot-ready)
|
|
|
|
- Contract-driven deploys with a versioned reusable workflow
|
|
- Module catalog (primitives + modules) with validated examples
|
|
- Zero-trust OIDC + ABAC on GitHub Actions runners
|
|
- Security + policy checks before infra creation (Checkov; Wiz + Kyverno ready)
|
|
- Confidence signal (6 inputs, per-env thresholds) gating promotion
|
|
- Hash-chained, tamper-evident evidence outbox (RPO = 0)
|
|
- Encryption by default + per-stack customer-managed keys
|
|
- Deletion protection by default + safe decommission with SRE gates
|
|
- Uptime monitoring deployed automatically with every stack
|
|
- Platform-managed environments + friendly onboarding
|
|
- Engine-agnostic core (1 adapter: Terraform) + VCS-agnostic ingestion
|
|
|
|
</td>
|
|
<td style="width: 48%; border: none; padding-left: 12px;">
|
|
|
|
**Planned** (on the roadmap)
|
|
|
|
- Real OIDC federation on all platform runners
|
|
- HITL wiring for qa / prod / dr environments
|
|
- Full regulatory ledger: S3 Object Lock + JWS signatures + daily checkpoints
|
|
- Compliance milestone: GDPR, SOX, SOC2, DORA extension points
|
|
- Environment self-service provisioning
|
|
- Dynamic module creation from a contract (agentic citizen-developer flow)
|
|
- Pattern recognition compounds value over time
|
|
- Additional engine adapters (OpenTofu, Pulumi, Kubernetes CRDs)
|
|
- Deeper observability bootstrap (dashboards, runbooks, on-call)
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
# A6 — Glossary
|
|
|
|
| Term | Meaning |
|
|
|---|---|
|
|
| **OIDC** | OpenID Connect — federation protocol for short-lived tokens, no long-lived credentials |
|
|
| **ABAC** | Attribute-Based Access Control — access scoped by resource tags + repo identity, not roles |
|
|
| **CMK** | Customer-Managed Key — per-stack encryption key, 90-day rotation, no shared keys |
|
|
| **CMDB** | Configuration Management Database — validates change requests for decommission |
|
|
| **RPO** | Recovery Point Objective — RPO = 0 means evidence is written synchronously, no data loss |
|
|
| **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 |
|
|
|
|
---
|
|
|
|
# A7 — Operating Model & Cost
|
|
|
|
<style>
|
|
section { font-size: 20px; }
|
|
table { font-size: 18px; }
|
|
</style>
|
|
|
|
Nova runs at **zero cloud cost** for day-to-day development. AWS spend was measured via Cost Explorer (`COST.md`, 2026-07-28):
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Total spend (8 days) | **$0.001883** |
|
|
| Daily average | $0.000235 |
|
|
| Projected monthly | ~$0.007 |
|
|
| Peak day | 2026-07-27 ($0.000867) |
|
|
|
|
- **S3 dominates** (98.8%, terraform state bucket) — no compute 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
|
|
- **Live-AWS verification is milestone-scoped, then torn down.** The pipeline now **defaults to plan-only** on every PR; `NOVA_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). Any spike > $1/day is an anomaly.
|
|
|
|
**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).
|
|
|
|
---
|
|
|
|
<!-- _class: title -->
|
|
<!-- _paginate: false -->
|
|
|
|
# A8 — Verified by Construction
|
|
|
|
<style>
|
|
section { font-size: 20px; }
|
|
</style>
|
|
|
|
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 `examples/{simple,complex}.yml` 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); `NOVA_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.
|
|
|
|
The v1.10 lesson is the negative space: a 918-line adapter with type-specific branches decayed silently. The ~80-line stateless adapter + the milestone regression gate are the structural fix. |