docs(P05): complete shell-reproducibility-tests-docs phase

---ci--- project: nova-platform phase: 5 milestone: v1.0 status: complete ---/ci--- P5 complete: shell scripts, test suite, docs. 76 tests pass. Happy paths A+B green. AC-8 clean. REQ-20,21,22,29,30,31,32,33,34,35,36,37,38 covered.
2026-08-24 17:53:53 +00:00
parent 756100ab17
commit e376929181
14 changed files with 979 additions and 9 deletions
@@ -1,21 +1,25 @@
 {
-  "phase": 4,
+  "phase": 5,
  "stage": "verify",
  "milestone": "v1.0",
  "phase_role": "execution",
  "attempts": 0,
-  "updated_at": "2026-08-20T20:15:00Z",
+  "updated_at": "2026-08-20T20:45:00Z",
  "project": "nova-platform",
  "milestone_branch": "milestone/v1.0-nova-platform",
-  "phase_branch": "phase/04-l2-patterns-bootstrap-platform",
+  "phase_branch": "phase/05-shell-reproducibility-tests-docs",
  "phase_0_ship": {"tag": "v0.1.0", "local_only": true},
  "phase_1_ship": {"tag": "v0.1.1", "local_only": true},
  "phase_2_ship": {"tag": "v0.1.2", "local_only": true},
  "phase_3_ship": {"tag": "v0.1.3", "local_only": true},
-  "phase_4_verify": {
+  "phase_4_ship": {"tag": "v0.1.4", "local_only": true},
+  "phase_5_verify": {
    "tests_pass": true,
-    "tests_count": 68,
-    "reqs_covered": ["REQ-12", "REQ-14", "REQ-15", "REQ-16", "REQ-17", "REQ-18", "REQ-19", "REQ-22"]
+    "tests_count": 76,
+    "reqs_covered": ["REQ-20", "REQ-21", "REQ-22", "REQ-29", "REQ-30", "REQ-31", "REQ-32", "REQ-33", "REQ-34", "REQ-35", "REQ-36", "REQ-37", "REQ-38"],
+    "happy_path_a": "run_platform.sh --check-only → === PLATFORM CHECK OK ===",
+    "happy_path_b": "run_ci.sh → === CI PIPELINE OK ===",
+    "ac_8_grep": "clean"
  },
-  "next_phase": "phase/05-shell-reproducibility-tests-docs"
+  "next_phase": "phase/06-final-review-ship"
 }
@@ -0,0 +1,127 @@
+# Nova Platform
+
+> Nova Platform — infrastructure delivery, simplified. A consumer declares
+> intent in a YAML contract; the platform resolves it to a stack, compiles
+> it through the Terraform adapter, and applies it. Every deployment is
+> reproducible from the shell, not just in CI.
+
+Nova Platform is the **infrastructure-delivery core** of the Nova model.
+The DevSecOps, identity, audit-ledger, and central CI-pipeline-contract
+machinery of the reference are intentionally removed. What remains: a
+consumer writes a small YAML contract that names one or more modules by
+name + version, selects an environment, and supplies module-specific
+inputs. The platform resolves the contract to a stack instance, compiles
+it through the Terraform adapter, and applies it.
+
+- **Consumer guide:** [`docs/consumer-guide.md`](docs/consumer-guide.md)
+- **Contracts:** [`docs/contracts/`](docs/contracts/index.md)
+- **Environments:** [`docs/environments/`](docs/environments/index.md)
+- **Architecture:** [`docs/architecture.md`](docs/architecture.md)
+- **Modules:** [`docs/modules/`](docs/modules/index.md)
+
+## How to run
+
+### Quick start (offline, no AWS required)
+
+The fastest way to verify the platform works — no AWS credentials, no
+bootstrap, no cost.
+
+```bash
+# Install test dependencies
+pip install -r requirements-test.txt
+
+# 1. Run the test suite (all offline)
+python3 -m pytest tests/ -q
+
+# 2. Run the platform in check-only mode (offline — contract -> resolve ->
+#    adapter -> structure validation). Uses the default sample contract.
+bash scripts/run_platform.sh --check-only contracts/static-assets.yml
+# Expected: "=== PLATFORM CHECK OK ==="
+
+# 3. Reproduce the full CI pipeline locally (lint -> test -> check-only)
+bash scripts/run_ci.sh
+# Expected: "=== CI PIPELINE OK ==="
+
+# Show all run_platform.sh flags:
+bash scripts/run_platform.sh --help
+```
+
+### Run against live AWS (requires credentials + bootstrap)
+
+> Prerequisites: a platform-managed environment (see
+> [docs/environments/](docs/environments/index.md); `core/environments/dev.json`
+> is the sample), AWS credentials for dev (in `.ciagent/.env.secrets`,
+> gitignored; see [Credentials](#credentials)), `terraform` (pin `>= 1.9, < 1.10`),
+> `python3` + `boto3` + `jsonschema` + `pyyaml`.
+
+```bash
+# 1. Bootstrap the AWS state backend + runner IAM user (one-time, idempotent)
+#    See terraform/bootstrap/README.md for the full runbook.
+export NOVA_BOOTSTRAP_AWS_ACCESS_KEY_ID="<root key>"
+export NOVA_BOOTSTRAP_AWS_SECRET_ACCESS_KEY="<root secret>"
+export AWS_DEFAULT_REGION="us-east-1"
+python3 terraform/bootstrap/create_state_backend.py
+python3 terraform/bootstrap/create_iam_user.py   # prints the initial key
+bash scripts/rotate_spike_key.sh                  # writes .ciagent/.env.secrets
+
+# 2. Run the full platform pipeline (contract -> environment check -> stack ->
+#    adapter -> terraform init/validate/plan -> apply).
+bash scripts/run_platform.sh contracts/microservice.yml
+# Expected: "=== PLATFORM APPLY OK ==="
+
+# Or plan-only (contract -> stack -> adapter -> terraform plan; no apply):
+bash scripts/run_platform.sh --plan-only contracts/static-assets.yml
+
+# Add --quiet to suppress streaming (output to log files only):
+bash scripts/run_platform.sh --quiet contracts/static-assets.yml
+```
+
+### run_platform.sh flags (D-031)
+
+| Flag | Mode | AWS required | Description |
+|------|------|--------------|-------------|
+| `--check-only` | offline | no | contract → resolve → adapter → structure validation |
+| `--plan-only` | AWS | yes | above + `terraform init`/`validate`/`plan` (no apply) |
+| `--quiet` | any | — | suppress streaming output |
+| `-h`, `--help` | — | — | show usage |
+| *(none)* | apply | yes | full path: above + `terraform apply -auto-approve` |
+
+## Repository layout
+
+| Path | Purpose | Status |
+|------|---------|--------|
+| `core/` | Platform code: contract resolver, environment check, environments | active |
+| `schemas/` | JSON Schemas (draft 2020-12): contract, stack, environment | active |
+| `adapters/terraform/` | The Terraform adapter — the only engine-specific code | active |
+| `terraform/` | State backend (S3 + DynamoDB) + bootstrap scripts + platform/onboarding/ci-vpc | active |
+| `modules/` | L1 primitives (13) + L2 patterns (2) + `registry.json`. Each module has `interface.json` + `terraform/` | active |
+| `contracts/` | Sample consumer contracts (`static-assets.yml`, `microservice.yml`) + per-env variants | active |
+| `scripts/` | `run_platform.sh` (pipeline runner), `run_ci.sh` (local CI mirror), `rotate_spike_key.sh` | active |
+| `tests/` | Pytest suite (all offline — resolver, adapter, schemas, engine boundary, environment check) | active |
+| `docs/` | Documentation: consumer guide, contracts, environments, architecture, modules | active |
+| `.ciagent/` | CIAgent config + locked decisions (`ARCHITECTURE.md`, `PROJECT.md`, `CLARIFY.md`) | active |
+
+## Credentials
+
+Nova Platform uses a **static AWS key** for dev/local operation. There is no
+zero-trust federation layer in v1.0 — that is out of scope.
+
+- The runner key is stored in **`.ciagent/.env.secrets`** (gitignored,
+  `chmod 600`) using the `NOVA_AWS_*` prefix (D-032):
+  `NOVA_AWS_ACCESS_KEY_ID`, `NOVA_AWS_SECRET_ACCESS_KEY`.
+- `scripts/run_platform.sh` copies `NOVA_AWS_*` to the standard `AWS_*`
+  env vars before invoking Terraform, then unsets the `NOVA_*` copies.
+- Bootstrap uses a one-shot root key via `NOVA_BOOTSTRAP_AWS_*` env vars
+  (never committed, never echoed). See
+  [`terraform/bootstrap/README.md`](terraform/bootstrap/README.md) for the
+  full bootstrap runbook (state backend + runner IAM user + key rotation).
+- Onboarding creates a per-consumer IAM **role** (cross-account assume-role
+  pattern, D-025) — not a user, not federation. See
+  `terraform/onboarding/main.tf`.
+
+## Consumer guide
+
+A step-by-step guide for a consumer to create a repo, write a contract,
+validate it offline, and run it against AWS is at
+[`docs/consumer-guide.md`](docs/consumer-guide.md). The guide is generic
+across all modules; `static-assets` is the worked example.
@@ -153,6 +153,7 @@ def resolve(contract, registry, modules_dir, environments_dir=None,

 def main(argv=None):
    import sys
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
    argv = argv or sys.argv[1:]
    if len(argv) < 2:
        print("usage: contract_resolver.py <contract.yaml> [out.json]",
@@ -0,0 +1,130 @@
+# Architecture
+
+> **Status:** v1.0 (current). This document mirrors `.ciagent/ARCHITECTURE.md`.
+> Where the two conflict, `.ciagent/ARCHITECTURE.md` wins.
+
+## 0. Purpose
+
+Nova Platform is the **infrastructure-delivery core**. A consumer declares
+intent in a YAML contract; the platform resolves it to a stack, compiles it
+through the Terraform adapter, and applies it. The DevSecOps, identity,
+audit-ledger, and central CI-pipeline-contract machinery of the Nova
+reference are intentionally removed — see the OOS list below.
+
+## 1. Layers (4)
+
+```
+┌──────────────────────────────────────────────────────┐
+│  1. Contract Surface      schemas/contract.schema.json
+│                           contracts/*.yml (samples)
+├──────────────────────────────────────────────────────┤
+│  2. Resolution            core/contract_resolver.py
+│                           core/environment_check.py
+│                           schemas/stack.schema.json
+├──────────────────────────────────────────────────────┤
+│  3. Engine Adapter        adapters/terraform/ (the only
+│  (only engine-specific)   engine-specific code)
+├──────────────────────────────────────────────────────┤
+│  4. Apply                 terraform/ (bootstrap, modules)
+│                           scripts/run_platform.sh
+└──────────────────────────────────────────────────────┘
+```
+
+### Layer 1 — Contract Surface
+
+A consumer writes a small YAML contract. The `infrastructure` field is an
+**array** (D-015), not a map:
+
+```yaml
+id: stsi
+name: My Static Site
+environment: dev
+infrastructure:
+  - module: static-assets
+    version: "1.0.0"
+    inputs:
+      bucket_name: my-static-site-assets
+      index_document: index.html
+```
+
+Validated against `schemas/contract.schema.json`. The contract is the only
+consumer-facing surface. It is engine-agnostic — no `aws_*` terms.
+
+### Layer 2 — Resolution
+
+`core/contract_resolver.py` resolves a validated contract to a Stack
+instance (a typed structure conforming to `schemas/stack.schema.json`).
+Resolution is pure: contract in, stack out. No I/O beyond local file reads
+for module metadata (D-011). No engine terms.
+
+`core/environment_check.py` validates that the named environment exists in
+`core/environments/*.json` and returns its definition. Environments are
+platform-managed (consumers provide no AWS account, VPC, or state bucket).
+
+Interpolation (D-016): the resolver expands `${env.<field>}` and
+`${contract.<field>}` tokens after the environment is loaded. Unknown tokens
+raise `ValueError`.
+
+### Layer 3 — Engine Adapter
+
+`adapters/terraform/` is the only engine-specific code. It takes a Stack
+and emits Terraform (`module "x" { source = "../../modules/..." }` blocks).
+The adapter is a stateless assembler — lifecycle ownership belongs to
+Terraform via the shell orchestrator. This is the only place `aws_*` /
+Terraform terms appear.
+
+### Layer 4 — Apply
+
+`scripts/run_platform.sh` orchestrates: contract → resolve → adapter →
+`terraform init` → `terraform plan` → `terraform apply`. Modes (D-031):
+`--check-only` (offline, structure validation), `--plan-only` (no apply),
+full (apply). `--quiet` suppresses streaming.
+
+## 2. Engine Boundary (Enforced)
+
+The engine boundary is strict. Code outside `adapters/terraform/` MUST NOT
+contain engine-specific terms (`aws_s3_bucket`, `aws_*`, Terraform HCL).
+This invariant is verified by tests (`tests/test_engine_boundary.py`,
+scope per D-034: `.py` files in `core/`, `schemas/`, `contracts/`,
+`tests/`, `scripts/`, root — excluding `adapters/terraform/`, `modules/`,
+`.tf`/`.md`/`.json` data files).
+
+## 3. What is NOT here (intentionally removed vs the reference)
+
+Nova Platform is a simplified, infrastructure-only platform. The following
+reference features are **out of scope** for v1.0:
+
+- No confidence signal — no score gating apply.
+- No audit outbox — no hash-chained evidence events.
+- No policy engine / policy adapter — no policy checks.
+- No identity layer, no attribute-based authorization, no human-in-the-loop
+  approval gates.
+- No reusable CI workflow — local shell only (`scripts/run_ci.sh`).
+- No central pipeline contract — no `pipelines/` directory.
+- No platform telemetry / metrics.
+- No decommission transform, env-transition transform, or onboarding flow
+  beyond bootstrap.
+- No leadership decks or slide rendering.
+
+## 4. Module Catalog
+
+L1 primitives (single resources) + L2 patterns (composites of primitives).
+Each module has an `interface.json` (inputs/outputs, no engine terms) and a
+`terraform/` directory. `modules/registry.json` indexes every module +
+version.
+
+**L1 (primitives — 13):** `s3`, `vpc`, `ecs-cluster`, `ecs-service`,
+`iam-role`, `alb`, `ecr`, `cloudfront`, `waf`, `rds`, `kms-key`,
+`dynamodb`, `uptime`.
+
+**L2 (patterns — 2):**
+
+| Module | Composes (D-038) | Description |
+|--------|------------------|-------------|
+| `microservice` | vpc + ecs-cluster + ecs-service + iam-role + ecr + alb (6 L1s) | Container microservice with a public ALB |
+| `static-assets` | s3 + cloudfront + kms-key (3 L1s) | Static site fronted by CloudFront |
+
+L2 modules are opaque stack entries (D-012): the resolver does not expand
+their children. The L2's `terraform/main.tf` composes L1 modules internally
+via `module` blocks. See [`docs/modules/index.md`](modules/index.md) for the
+full catalog and each module's README.
@@ -0,0 +1,208 @@
+# Consumer Guide — Declare intent, deploy to AWS
+
+This guide walks a consumer through creating a repo, writing a contract,
+validating it offline, and running it against AWS. It is **generic** across
+all modules in the registry; `static-assets` is the worked example, but
+every step applies to `microservice` and any future module.
+
+## The model
+
+You write a contract YAML file and the platform does the rest. Your
+repository contains only your application code and your contracts. You do
+not write infrastructure modules or adapter code.
+
+```mermaid
+flowchart LR
+    A["your repo<br/>(app code + contract)"] -->|run_platform.sh| B
+    B["platform<br/>(resolver + adapter + modules)"] -->|contract -> stack -> terraform -> apply| C
+    C["your resources in AWS"]
+```
+
+## Prerequisites
+
+- **A consumer repository** for your application code + contract.
+- **A platform-managed environment** bound to your repo. The platform team
+  provisions the AWS account, network, and state backend. See
+  [Environments](environments/index.md).
+- **AWS credentials** for the target environment, in `.ciagent/.env.secrets`
+  (gitignored) using the `NOVA_AWS_*` prefix. See the
+  [platform README](../README.md#credentials) and
+  [`terraform/bootstrap/README.md`](../terraform/bootstrap/README.md).
+
+## Step 1 — Create a consumer repo
+
+Create a repository for your application. The top level holds your app
+code; your contract lives at the repo root (or wherever you point
+`run_platform.sh`). Example for a static site:
+
+```
+my-static-site/
+  index.html
+  assets/
+    style.css
+    logo.png
+  contract.yml
+```
+
+Example for a microservice:
+
+```
+my-microservice/
+  app.py
+  Dockerfile
+  contract.yml
+```
+
+## Step 2 — Define the contract
+
+Write `contract.yml`. The `static-assets` example:
+
+```yaml
+id: stsi
+name: Static Assets Site
+environment: dev
+infrastructure:
+  - module: static-assets
+    version: "1.0.0"
+    inputs:
+      bucket_name: "${env.environment}-${contract.id}-assets"
+      index_document: index.html
+```
+
+A `microservice` example:
+
+```yaml
+id: msvc
+name: Microservice
+environment: dev
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
+```
+
+### Contract fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Short operational acronym (`^[a-z][a-z0-9-]{2,5}$`, 3-6 chars). Becomes the stack name used for the Terraform state key and resource naming prefix. Stable across deploys and environment promotions. |
+| `name` | string | yes | Full human-readable stack name (min 3 chars). |
+| `environment` | string | yes | The platform-managed environment to deploy to (`dev`/`qa`/`prod`/`dr`). See [Environments](environments/index.md). |
+| `infrastructure` | array | yes | **Array** of modules to deploy (D-015). Each entry carries a `module` name (matching a registry key), an optional `version` (defaults to latest non-deprecated), and required `inputs`. One entry = single-module deploy; N entries = multi-module manifest. |
+
+### Infrastructure item fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `module` | string | yes | Module name from `modules/registry.json` (`^[a-z][a-z0-9-]*$`). |
+| `version` | string | no | Semver pin `X.Y.Z`. Omitted = latest non-deprecated version. |
+| `inputs` | object | yes | Module-specific inputs (see the module's README). No `aws_*` keys — the contract is engine-agnostic. |
+
+Each module declares its inputs in its `interface.json`. Consult the
+[module catalog](modules/index.md) for the full list, or read the module's
+own README under `modules/l1/<name>/` or `modules/l2/<name>/`.
+
+The contract is validated against `schemas/contract.schema.json`. An invalid
+contract (missing field, unknown module, wrong type) fails at the
+validate-contract stage with a clear error.
+
+### Interpolation reference (D-016)
+
+The resolver expands `${env.*}` and `${contract.*}` tokens after the
+environment is loaded. Unknown tokens raise `ValueError` (fail loud).
+Expansion is recursive (nested map/list values expand too).
+
+| Token | Resolves to | Example |
+|-------|-------------|---------|
+| `${env.name}` | the environment name | `dev` |
+| `${env.region}` | the environment's AWS region | `us-east-1` |
+| `${env.account_id}` | the environment's AWS account id | `000000000000` |
+| `${env.state_backend.bucket}` | the environment's state bucket | `nova-tfstate-dev-us-east-1` |
+| `${env.state_backend.lock_table}` | the environment's lock table | `nova-tfstate-locks` |
+| `${env.network.vpc_cidr}` | the environment's VPC CIDR | `10.0.0.0/16` |
+| `${contract.id}` | the contract's operational acronym | `stsi` |
+| `${contract.name}` | the contract's name field | `Static Assets Site` |
+| `${contract.environment}` | the contract's environment field | `dev` |
+
+## Step 3 — Validate offline (no AWS required)
+
+Before touching AWS, validate the contract end-to-end offline. Clone the
+Nova Platform repo and run `--check-only` against your contract:
+
+```bash
+bash scripts/run_platform.sh --check-only path/to/your/contract.yml
+# Expected: "=== PLATFORM CHECK OK ==="
+```
+
+This runs: environment check → contract schema validation → resolve to
+stack → adapter compiles to HCL → output structure validation. No AWS
+credentials are needed.
+
+## Step 4 — Run against live AWS
+
+Once the contract validates offline, run the full pipeline against AWS.
+Ensure your credentials are in `.ciagent/.env.secrets` (see
+[Credentials](../README.md#credentials)):
+
+```bash
+bash scripts/run_platform.sh contracts/static-assets.yml
+# Expected: "=== PLATFORM APPLY OK ==="
+```
+
+The full path: environment check → validate contract → resolve to stack →
+adapter compiles to HCL → load AWS credentials → `terraform init` →
+`terraform validate` → `terraform plan` → `terraform apply -auto-approve`.
+
+To stop before apply (review the plan only):
+
+```bash
+bash scripts/run_platform.sh --plan-only contracts/static-assets.yml
+# Expected: "=== PLATFORM PLAN OK ==="
+```
+
+## Step 5 — What gets created
+
+After a successful `dev` run, the resources declared by your module's
+pattern exist in your AWS account.
+
+For the `static-assets` example (s3 + cloudfront + kms-key, D-038):
+
+- An **S3 bucket** (named via your `bucket_name` input, interpolation
+  expanded) with versioning enabled.
+- A **CloudFront distribution** with the S3 bucket as the origin.
+- A **KMS key** for SSE.
+
+For other modules, consult the module's README
+(`modules/l1/<name>/README.md` or `modules/l2/<name>/README.md`) for the
+exact resources created.
+
+## Step 6 — Upload your content (static-assets example)
+
+The platform provisions the infrastructure; you upload your content. For the
+`static-assets` module:
+
+```bash
+aws s3 sync ./assets s3://<your-bucket-name>/
+```
+
+For a `microservice`, the platform provisions the ECS service and ALB; you
+push your container image to the ECR repo the platform created.
+
+## Reference
+
+| Resource | Path | Description |
+|----------|------|-------------|
+| Contract schema | `schemas/contract.schema.json` | JSON Schema for consumer contracts. |
+| Stack schema | `schemas/stack.schema.json` | JSON Schema for the resolved stack instance. |
+| Module catalog | [modules/](modules/index.md) | All primitives and modules. |
+| Sample contract | `contracts/static-assets.yml` | The reference example contract. |
+| Sample contract | `contracts/microservice.yml` | The microservice example contract. |
+| Module examples | `modules/<name>/examples/` | Validated per-module example contracts. |
+| Contract resolver | `core/contract_resolver.py` | Resolves contracts to stack instances. |
+| Terraform adapter | `adapters/terraform/adapter.py` | Compiles stack instances to Terraform. |
+| Pipeline runner | `scripts/run_platform.sh` | The pipeline runner. |
+| Environments | [environments/](environments/index.md) | Platform-managed environments. |
+| Platform README | `README.md` | How the platform works + how to run it. |
+| Credentials | `README.md#credentials` | The static-key model + bootstrap runbook. |
@@ -0,0 +1,139 @@
+# Contracts
+
+A consumer declares intent in a **contract** — a small YAML file that names
+infrastructure (one or more modules), selects an environment, and supplies
+module-specific inputs. The platform validates, resolves, and deploys it.
+
+## The contract file
+
+A minimal example (the `static-assets` module):
+
+```yaml
+id: stsi
+name: Static Assets Site
+environment: dev
+infrastructure:
+  - module: static-assets
+    version: "1.0.0"
+    inputs:
+      bucket_name: "${env.environment}-${contract.id}-assets"
+      index_document: index.html
+```
+
+A `microservice` example:
+
+```yaml
+id: msvc
+name: Microservice
+environment: dev
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
+```
+
+## Array-based infrastructure (D-015)
+
+The `infrastructure` field is an **array** of module entries, not a map
+keyed by module name. This is a locked deviation from the Nova reference
+(D-015). Each entry is an object with `module`, `version` (optional), and
+`inputs`.
+
+One entry = single-module deploy. N entries = multi-module manifest deployed
+in one pipeline run:
+
+```yaml
+id: app
+name: Pricing Service API
+environment: dev
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs: { ... }
+  - module: static-assets
+    version: "1.0.0"
+    inputs: { ... }
+```
+
+All modules deploy to the same `environment` in one pipeline run.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Short operational acronym (`^[a-z][a-z0-9-]{2,5}$`, 3-6 chars). Becomes the stack name used for the Terraform state key and resource naming prefix. Stable across deploys and environment promotions. |
+| `name` | string | yes | Full human-readable stack name (min 3 chars). |
+| `environment` | string | yes | The platform-managed environment to deploy to (`dev`/`qa`/`prod`/`dr`). See [Environments](../environments/index.md). |
+| `infrastructure` | array | yes | Array of modules to deploy (D-015). `minItems: 1`. |
+
+### Infrastructure item fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `module` | string | yes | Module name from `modules/registry.json` (`^[a-z][a-z0-9-]*$`). |
+| `version` | string | no | Semver pin (`^\d+\.\d+\.\d+$`). Omitted = latest non-deprecated version from the registry. |
+| `inputs` | object | yes | Module-specific inputs (see the module's README / `interface.json`). No `aws_*` keys — the contract is engine-agnostic. |
+
+## Validation
+
+The contract is validated against
+[`schemas/contract.schema.json`](../../schemas/contract.schema.json). An
+invalid contract (missing field, unknown module, wrong type) fails at the
+validate-contract stage with a clear error.
+
+## Interpolation tokens (D-016)
+
+The resolver expands `${env.*}` and `${contract.*}` tokens after the
+environment is loaded. Unknown tokens raise `ValueError` (fail loud).
+Expansion is recursive (nested map/list values expand too).
+
+| Token | Resolves to | Example |
+|-------|-------------|---------|
+| `${env.name}` | the environment name | `dev` |
+| `${env.region}` | the environment's AWS region | `us-east-1` |
+| `${env.account_id}` | the environment's AWS account id | `000000000000` |
+| `${env.state_backend.bucket}` | the environment's state bucket | `nova-tfstate-dev-us-east-1` |
+| `${env.state_backend.lock_table}` | the environment's lock table | `nova-tfstate-locks` |
+| `${env.network.vpc_cidr}` | the environment's VPC CIDR | `10.0.0.0/16` |
+| `${env.network.azs}` | the environment's availability zones | `["us-east-1a","us-east-1b"]` |
+| `${contract.id}` | the contract's operational acronym | `stsi` |
+| `${contract.name}` | the contract's name field | `Static Assets Site` |
+| `${contract.environment}` | the contract's environment field | `dev` |
+
+## Sample contracts
+
+Two reference examples exist in `contracts/`:
+
+- [`contracts/static-assets.yml`](../../contracts/static-assets.yml) — the
+  `static-assets` module (s3 + cloudfront + kms-key, D-038).
+- [`contracts/microservice.yml`](../../contracts/microservice.yml) — the
+  `microservice` module (vpc + ecs-cluster + ecs-service + iam-role + ecr +
+  alb, D-038).
+
+Additionally, every module has a `modules/<name>/examples/` directory with
+validated example contracts. See the [module catalog](../modules/index.md)
+for the full list.
+
+## Per-environment variants (D-033)
+
+Each sample contract has per-environment variants that differ **only** in
+the `environment` field — all other fields are identical. Interpolation
+resolves environment-specific values at resolver time.
+
+| File | Environment |
+|------|-------------|
+| `contracts/static-assets.yml` | dev (default) |
+| `contracts/static-assets.dev.yml` | dev |
+| `contracts/static-assets.qa.yml` | qa |
+| `contracts/static-assets.prod.yml` | prod |
+| `contracts/static-assets.dr.yml` | dr |
+| `contracts/microservice.yml` | dev (default) |
+| `contracts/microservice.dev.yml` | dev |
+| `contracts/microservice.qa.yml` | qa |
+| `contracts/microservice.prod.yml` | prod |
+| `contracts/microservice.dr.yml` | dr |
+
+Promotion = running the pipeline against the matching variant. See the
+[Consumer Guide](../consumer-guide.md) for the end-to-end flow.
@@ -0,0 +1,104 @@
+# Environments
+
+A consumer does **not** provide an AWS account, a VPC, a subnet, or an S3
+state bucket. The platform manages environments.
+
+## What an environment is
+
+A named environment is a **platform-owned** bundle of:
+
+- An **AWS account** (or a scoped partition of one).
+- A **network** (VPC + subnets / AZs).
+- A **state backend** (an S3 bucket + DynamoDB lock table for Terraform
+  state).
+
+A consumer selects an environment **by name** in their contract:
+
+```yaml
+environment: dev
+```
+
+The platform resolves the name to the underlying account/network/state
+backend at run time. The consumer never sees the raw credentials.
+
+## Environment definition shape (D-018)
+
+Each environment is a JSON file in `core/environments/`. The field set is
+reduced from the reference — the IAM role, autonomy, and confidence
+threshold fields are out of scope for v1.0.
+
+`core/environments/dev.json` (the sample):
+
+```json
+{
+  "name": "dev",
+  "description": "Sample dev environment for offline/local testing. account_id placeholder (000000000000) for offline mode.",
+  "account_id": "000000000000",
+  "region": "us-east-1",
+  "state_backend": {
+    "bucket": "nova-tfstate-dev-us-east-1",
+    "lock_table": "nova-tfstate-locks"
+  },
+  "network": {
+    "vpc_cidr": "10.0.0.0/16",
+    "azs": ["us-east-1a", "us-east-1b"]
+  }
+}
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | The environment name (`dev`/`qa`/`prod`/`dr`). |
+| `description` | string | no | Human-readable description. |
+| `account_id` | string | yes | The AWS account id (placeholder `000000000000` for offline dev). |
+| `region` | string | yes | The AWS region. |
+| `state_backend.bucket` | string | yes | The S3 state bucket name. |
+| `state_backend.lock_table` | string | yes | The DynamoDB lock table name (`nova-tfstate-locks` per D-022). |
+| `network.vpc_cidr` | string | yes | The VPC CIDR block. |
+| `network.azs` | array | yes | The availability zones. |
+
+### Dropped from the reference (D-018)
+
+- `runner_role_arn` — identity/authorization is out of scope.
+- `autonomy` — human-in-the-loop gates are out of scope.
+- `confidence_threshold` — the confidence signal is out of scope.
+
+## State backend (D-022)
+
+The Terraform state backend uses a dedicated DynamoDB lock table named
+`nova-tfstate-locks` (NOT `nova-outbox` — the audit outbox is out of scope
+for v1.0). The S3 state bucket is named `nova-tfstate-<account>-<region>`
+with versioning enabled. See
+[`terraform/bootstrap/README.md`](../../terraform/bootstrap/README.md) for
+the bootstrap runbook that creates both.
+
+## Autonomy by environment
+
+| Environment | Autonomy | Operator action |
+|-------------|----------|-----------------|
+| dev | Fully autonomous | None — `terraform apply -auto-approve` runs automatically. |
+| qa | Manual | An operator runs `run_platform.sh` against the `qa` contract. |
+| prod | Manual | An operator runs `run_platform.sh` against the `prod` contract. |
+| dr | Manual | An operator runs `run_platform.sh` against the `dr` contract. |
+
+`dev` is the only autonomous environment. Higher environments require a
+human operator to invoke the pipeline against the environment's contract
+variant. There are no automated gates or attestation steps — those are out
+of scope for v1.0. Staging does not exist.
+
+## Onboarding scaffold (current state)
+
+The platform repo ships a minimal onboarding scaffold:
+
+- [`core/environments/`](../../core/environments/) — environment definitions
+  (a sample `dev.json`).
+- `core/environment_check.py` — checks whether an environment is defined
+  for a given contract's environment name; raises `EnvironmentNotFoundError`
+  when none is defined (D-019).
+- `scripts/run_platform.sh` calls the check before contract validation.
+
+The scaffold is minimal: provisioning a new environment is a platform-team
+action today (bootstrap the state backend + network). Self-service
+environment provisioning is a future milestone.
@@ -123,5 +123,5 @@ in this repo ship a Terraform adapter under `terraform/`.

 | Module           | Composes                                  | Description                                  |
 |------------------|-------------------------------------------|----------------------------------------------|
-| `microservice`   | vpc + ecs-cluster + ecs-service + alb + ecr | Container microservice with public ALB     |
-| `static-assets`  | s3 + cloudfront                            | Static site fronted by CloudFront            |
+| `microservice`   | vpc + ecs-cluster + ecs-service + iam-role + ecr + alb | Container microservice with public ALB (D-038) |
+| `static-assets`  | s3 + cloudfront + kms-key                 | Static site fronted by CloudFront (D-038)   |
@@ -0,0 +1,38 @@
+[project]
+name = "nova-platform"
+version = "1.0.0"
+description = "Nova Platform — simplified infrastructure delivery (contract -> resolve -> terraform adapter -> apply)"
+requires-python = ">=3.11"
+dependencies = [
+    "boto3>=1.34",
+    "jsonschema>=4.20",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "moto[dynamodb]>=5.0",
+    "jsonschema>=4.20",
+    "pyyaml>=6.0",
+    "boto3>=1.34",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+markers = [
+    "offline: offline tests (no AWS)",
+    "slow: slow tests",
+    "shell: shell-invocation tests (excluded from run_ci.sh to avoid recursion)",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning:botocore.*",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["core*", "adapters*"]
@@ -0,0 +1,5 @@
+pytest>=8.0
+moto[dynamodb]>=5.0
+jsonschema>=4.20
+pyyaml>=6.0
+boto3>=1.34
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Nova Platform — run_ci.sh
+#
+# Local CI pipeline mirror: lint (py_compile) -> test (pytest) ->
+# check-only (run_platform.sh --check-only).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+QUIET=0
+[ "${1:-}" = "--quiet" ] && QUIET=1
+
+banner() { [ "$QUIET" -eq 0 ] && echo "── $1 ──"; }
+
+banner "Stage 1/3: lint (py_compile)"
+python3 -m py_compile $(find core/ adapters/ scripts/ -name '*.py' -not -path '*/__pycache__/*')
+echo "lint: OK"
+
+banner "Stage 2/3: test (pytest)"
+python3 -m pytest tests/ -q --tb=short -m "not shell"
+echo "test: OK"
+
+banner "Stage 3/3: check-only (run_platform.sh --check-only)"
+bash scripts/run_platform.sh --check-only contracts/static-assets.yml
+echo "check-only: OK"
+
+echo "=== CI PIPELINE OK ==="
+echo "3 stages passed: lint, test, check-only"
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Nova Platform — run_platform.sh
+#
+# Orchestrates: contract -> resolve -> adapter -> apply.
+#
+# Flags (per D-031): --check-only, --plan-only, --quiet, --help (-h).
+# Default mode (no flag) = apply.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+CHECK_ONLY=0
+PLAN_ONLY=0
+QUIET=0
+CONTRACT=""
+
+_print_help() {
+  cat <<EOF
+usage: run_platform.sh [--check-only|--plan-only|--quiet|--help] [contract.yml]
+
+  --check-only   Offline validation: contract -> resolve -> adapter -> validate. No AWS.
+  --plan-only    AWS: above + terraform init/validate/plan. No apply.
+  --quiet        Suppress streaming output.
+  -h, --help     Show this help.
+
+Default (no flag): full apply path (AWS required).
+Default contract: contracts/static-assets.yml
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --check-only) CHECK_ONLY=1; shift;;
+    --plan-only) PLAN_ONLY=1; shift;;
+    --quiet) QUIET=1; shift;;
+    -h|--help) _print_help; exit 0;;
+    --*) echo "FAIL: unknown flag $1" >&2; exit 1;;
+    *) CONTRACT="$1"; shift;;
+  esac
+done
+
+[ -z "$CONTRACT" ] && CONTRACT="contracts/static-assets.yml"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+WORK="${NOVA_WORK_DIR:-/tmp/nova_platform_run}"
+TF_DIR="$WORK/tf"
+rm -rf "$WORK"; mkdir -p "$TF_DIR"
+
+banner() { [ "$QUIET" -eq 0 ] && echo "=== $* ==="; }
+
+banner "Step 0: environment check"
+python3 -c "
+import sys, json, yaml
+from pathlib import Path
+sys.path.insert(0, '.')
+from core import environment_check
+contract = yaml.safe_load(open('$CONTRACT'))
+env = environment_check.check(contract['environment'], Path('core/environments'))
+print(f'env: {env[\"name\"]} ({env[\"region\"]})')
+"
+
+banner "Step 1: validate contract"
+python3 -c "
+import json, yaml, jsonschema
+schema = json.load(open('schemas/contract.schema.json'))
+contract = yaml.safe_load(open('$CONTRACT'))
+jsonschema.validate(contract, schema)
+print('contract valid')
+"
+
+banner "Step 2: resolve contract -> stack"
+python3 core/contract_resolver.py "$CONTRACT" "$WORK/stack.json"
+python3 -c "import json; s=json.load(open('$WORK/stack.json')); print(f'resources: {len(s[\"resources\"])}')"
+
+banner "Step 3: adapter compiles stack -> HCL"
+python3 adapters/terraform/adapter.py "$WORK/stack.json" "$TF_DIR/main.tf"
+[ "$QUIET" -eq 0 ] && head -20 "$TF_DIR/main.tf"
+
+if [ "$CHECK_ONLY" -eq 1 ]; then
+  python3 -c "
+from pathlib import Path
+main = Path('$TF_DIR/main.tf')
+assert main.exists() and main.stat().st_size > 0, 'main.tf missing or empty'
+content = main.read_text()
+assert 'module \"' in content, 'no module blocks'
+print('output structure valid')
+"
+  echo "=== PLATFORM CHECK OK ==="
+  exit 0
+fi
+
+banner "Loading AWS credentials"
+if [ -f .ciagent/.env.secrets ]; then
+  set -a
+  . .ciagent/.env.secrets
+  set +a
+fi
+export AWS_ACCESS_KEY_ID="${NOVA_AWS_ACCESS_KEY_ID:-${AWS_ACCESS_KEY_ID:-}}"
+export AWS_SECRET_ACCESS_KEY="${NOVA_AWS_SECRET_ACCESS_KEY:-${AWS_SECRET_ACCESS_KEY:-}}"
+export AWS_DEFAULT_REGION="${AWS_DEFAULT_REGION:-us-east-1}"
+unset NOVA_AWS_ACCESS_KEY_ID NOVA_AWS_SECRET_ACCESS_KEY NOVA_FORGE_TOKEN 2>/dev/null || true
+[ -z "$AWS_ACCESS_KEY_ID" ] && fail "no AWS credentials (set NOVA_AWS_* in .ciagent/.env.secrets)"
+
+banner "Step 4: terraform init + validate + plan"
+( cd "$TF_DIR" && terraform init -backend=false && terraform validate && terraform plan -out=tfplan )
+
+if [ "$PLAN_ONLY" -eq 1 ]; then
+  echo "=== PLATFORM PLAN OK ==="
+  exit 0
+fi
+
+banner "Step 5: terraform apply"
+( cd "$TF_DIR" && terraform apply -auto-approve tfplan )
+echo "=== PLATFORM APPLY OK ==="
@@ -0,0 +1,32 @@
+"""Test scripts/run_ci.sh — REQ-30."""
+
+import subprocess
+
+import pytest
+
+from tests.conftest import ROOT
+
+pytestmark = pytest.mark.shell
+
+
+class TestRunCi:
+    def test_exits_zero(self):
+        result = subprocess.run(
+            ["bash", str(ROOT / "scripts" / "run_ci.sh")],
+            capture_output=True, text=True, cwd=str(ROOT),
+        )
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+
+    def test_banner(self):
+        result = subprocess.run(
+            ["bash", str(ROOT / "scripts" / "run_ci.sh")],
+            capture_output=True, text=True, cwd=str(ROOT),
+        )
+        assert "=== CI PIPELINE OK ===" in result.stdout
+
+    def test_three_stages_message(self):
+        result = subprocess.run(
+            ["bash", str(ROOT / "scripts" / "run_ci.sh")],
+            capture_output=True, text=True, cwd=str(ROOT),
+        )
+        assert "3 stages passed: lint, test, check-only" in result.stdout
@@ -0,0 +1,37 @@
+"""Test scripts/run_platform.sh --check-only — REQ-29."""
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tests.conftest import ROOT
+
+pytestmark = pytest.mark.shell
+
+
+class TestRunPlatformCheckOnly:
+    def test_check_only_exits_zero(self):
+        result = subprocess.run(
+            ["bash", str(ROOT / "scripts" / "run_platform.sh"),
+             "--check-only", "contracts/static-assets.yml"],
+            capture_output=True, text=True, cwd=str(ROOT),
+        )
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+
+    def test_check_only_banner(self):
+        result = subprocess.run(
+            ["bash", str(ROOT / "scripts" / "run_platform.sh"),
+             "--check-only", "contracts/static-assets.yml"],
+            capture_output=True, text=True, cwd=str(ROOT),
+        )
+        assert "=== PLATFORM CHECK OK ===" in result.stdout
+
+    def test_check_only_microservice(self):
+        result = subprocess.run(
+            ["bash", str(ROOT / "scripts" / "run_platform.sh"),
+             "--check-only", "contracts/microservice.yml"],
+            capture_output=True, text=True, cwd=str(ROOT),
+        )
+        assert result.returncode == 0
+        assert "=== PLATFORM CHECK OK ===" in result.stdout