Update docs/architecture.md
This commit is contained in:
@@ -23,33 +23,19 @@ Authoring principle: The vision is the source of truth for why [1]; this documen
|
||||
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). |
|
||||
|
||||
---
|
||||
@@ -141,15 +127,10 @@ Locked commitments (unchanged from v0.1):
|
||||
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.
|
||||
@@ -269,37 +250,23 @@ Sequence:
|
||||
### 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
|
||||
@@ -391,29 +358,17 @@ The confidence signal does not consume raw Checkov or Kyverno output. It consume
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user