acdl/docs/architecture.md

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):

{
  "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?