docs(P01): complete contract-surface-schemas-resolver phase

---ci--- project: nova-platform phase: 1 milestone: v1.0 status: complete phase_role: execution ---/ci--- P1 complete: contract schema, stack schema, environment schema, resolver, env_check, 10 sample contracts, 36 tests. REQ-01..06, 23..28 covered.
docs(P00): complete pre-execution phase (specify+clarify+research+plan+grill)
2026-08-24 17:31:00 +00:00 · 2026-08-24 17:26:06 +00:00
35 changed files with 2941 additions and 0 deletions
@@ -0,0 +1,116 @@
+# Nova Platform — Architecture
+
+> Simplified from the Nova reference. The reference's six cross-cutting
+> concerns (security, policy, confidence, outbox/audit, identity, CI
+> pipeline contract) are removed. What remains is the four-layer
+> infrastructure-delivery core.
+
+## Layers (4)
+
+```
+┌──────────────────────────────────────────────────────┐
+│  1. Contract Surface      schemas/contract.schema.json
+│                           contracts/*.yaml (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:
+
+```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, no engine terms.
+
+`core/environment_check.py` validates that the named environment exists
+in `core/environments/*.json` and that the caller is permitted to use
+it. Environments are platform-managed (consumers provide no AWS account,
+VPC, or state bucket).
+
+### 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:
+`--check-only` (offline, structure validation), `--plan-only` (no
+apply), full (apply). `--quiet` suppresses streaming.
+
+## 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`).
+
+## What is NOT here (intentionally removed vs the reference)
+
+- No `core/confidence_signal.py` — no score gating apply.
+- No `core/outbox_writer.py` — no hash-chained evidence events.
+- No `core/policy_engine.py` / `adapters/kyverno-json/` /
+  `adapters/wiz/` — no policy checks.
+- No `core/abac_evaluator.py` / `core/auth_store.py` /
+  `core/jws_attestation.py` / `core/kms_signing.py` /
+  `core/pat_lifecycle.py` / `core/separation_of_duties.py` /
+  `core/hitl_gates.py` / `core/attestation_matrix.py` /
+  `core/submission_readiness.py` — no identity/ABAC/HITL.
+- No `adapters/checkov/` custom rules — no Checkov.
+- No `.github/workflows/` — no CI pipeline (local shell only).
+- No `pipelines/` — no central pipeline contract.
+- No `schemas/pipeline.schema.json` /
+  `schemas/deploy-pipeline.schema.json` /
+  `schemas/policy_check_result.schema.json` /
+  `schemas/metrics_*.schema.json` — those schemas are dropped.
+- No `metrics/` — no platform telemetry.
+- No `core/regression_verify*.py` / `core/metrics/` — no regression or
+  metrics modules.
+- No leadership decks, PPTX rendering, marp slides.
+- No `core/env_transition.py` / `core/decommission_transform.py` /
+  `core/mode_resolver.py` / `core/onboarding.py` — no env transition,
+  decommission, mode resolution, or onboarding flow beyond bootstrap.
+
+## 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):** s3, vpc, ecs-cluster, ecs-service, iam-role, alb,
+ecr, cloudfront, waf, rds, kms-key, dynamodb, uptime.
+
+**L2 (patterns):** microservice (vpc + ecs-cluster + ecs-service +
+iam-role + ecr + alb — locked D-038), static-assets (s3 + cloudfront +
+kms-key — locked D-038, drops waf from reference).
@@ -0,0 +1,25 @@
+{
+  "phase": 1,
+  "stage": "verify",
+  "milestone": "v1.0",
+  "phase_role": "execution",
+  "attempts": 0,
+  "updated_at": "2026-08-20T19:00:00Z",
+  "project": "nova-platform",
+  "milestone_branch": "milestone/v1.0-nova-platform",
+  "phase_branch": "phase/01-contract-surface-schemas-resolver",
+  "phase_0_ship": {
+    "tag": "v0.1.0",
+    "merged_to_milestone": true,
+    "merge_commit": "7835c2a",
+    "phase_branch_deleted": true,
+    "local_only": true,
+    "release_pending": "NOVA_FORGE_TOKEN blank"
+  },
+  "phase_1_verify": {
+    "tests_pass": true,
+    "tests_count": 36,
+    "reqs_covered": ["REQ-01", "REQ-02", "REQ-03", "REQ-04", "REQ-05", "REQ-06", "REQ-23", "REQ-24", "REQ-27", "REQ-28"]
+  },
+  "next_phase": "phase/02-terraform-adapter-engine-boundary"
+}
@@ -0,0 +1,237 @@
+# CLARIFY — Nova Platform v1.0 (Phase 0)
+
+> 25 decisions (D-011..D-035) resolving remaining specification
+> ambiguities. Init already locked D-001..D-010. Autonomy: supervised
+> (present + wait for human review).
+
+## Architecturally significant (highest impact)
+
+### D-011: Resolver purity vs file I/O
+`resolve()` is declared pure (no I/O) in REQ-03 but must load
+`interface.json` / composition data from disk.
+- **Default:** Add `modules_dir: Path` as 3rd param. "No I/O" means no
+  network/side-effects — local file reads for module metadata are
+  permitted. The registry provides paths; the resolver reads the files.
+- Confidence: 0.82
+- Alternatives: [pre-enrich registry inline (truly pure); caller
+  pre-loads interfaces as 4th dict; take contract_path string like ref]
+
+### D-012: L2 representation — opaque vs expanded
+Does the resolver expand L2 compositions into individual L1 stack
+resources, or treat L2 as a single opaque resource?
+- **Default:** L2 is a single opaque resource. Stack has one entry:
+  `{module:"microservice", version, source:"modules/l2/microservice/terraform",
+  inputs}`. The L2's `terraform/main.tf` composes L1 internally via
+  `module` blocks. Resolver does NOT expand children.
+- Confidence: 0.88
+- Alternatives: [keep reference expansion (children/wires, needs richer
+  stack schema — contradicts REQ-04's flat shape); hybrid]
+
+### D-013: L2 file naming + registry `terraform_dir`
+REQ-12 says L2 has `interface.json` (reference uses `composition.json`).
+Reference L2 registry entries omit `terraform_dir` but the flat stack
+needs `source`.
+- **Default:** L2 uses `interface.json` (L2-level inputs/outputs, no
+  children/wires — those are in terraform/main.tf). L2 registry entries
+  DO include `terraform_dir: "modules/l2/<name>/terraform"` (deviation
+  from ref L2 entries which omit it — required by flat stack `source`).
+  `kind: "l2"` retained.
+- Confidence: 0.80
+- Alternatives: [keep `composition.json` name but simplified content;
+  keep ref L2 shape exactly]
+
+## Contract / schema details
+
+### D-015: Contract field constraints
+- **Default:** Keep ref `id` pattern `^[a-z][a-z0-9-]{2,5}$`, `name`
+  `minLength:3`. `version` OPTIONAL (defaults to latest non-deprecated).
+  `infrastructure[]` items: `module` (required), `version` (optional,
+  semver `^\d+\.\d+\.\d+$`), `inputs` (required, object,
+  `additionalProperties:false`).
+- Confidence: 0.85
+
+### D-016: Interpolation `${env.*}` / `${contract.*}`
+- **Default:** KEEP interpolation. Resolver expands `${env.<field>}` and
+  `${contract.<field>}` after environment_check loads env JSON. Sample
+  contracts use `${env.region}`, `${env.account_id}` for naming.
+  Unknown tokens raise `ValueError`.
+- Confidence: 0.78
+
+### D-017: schemas/environment.schema.json — keep or drop?
+- **Default:** KEEP but simplify to match reduced field set (D-018).
+  Validates `core/environments/*.json`.
+- Confidence: 0.70 *(below supervised threshold — escalate)*
+
+### D-033: Per-env contract variants
+- **Default:** Variants differ ONLY in `environment` field. All other
+  fields identical. Interpolation resolves per-env at resolver time.
+- Confidence: 0.85
+
+### D-035: `index_document` input — L1 s3 or L2 static-assets?
+- **Default:** `index_document` is an L2 `static-assets` input
+  (passthrough to s3 website config in L2 terraform). L1 `s3` does NOT
+  gain it (stays ref interface: `bucket_name`/`region`/`kms_key_arn`/
+  `enabled`).
+- Confidence: 0.80
+
+## Resolver / adapter / interface
+
+### D-014: L1 `interface.json` field set
+- **Default:** Keep `name`, `version`, `kind`, `type`, `description`,
+  `inputs`, `outputs`, `resources` (multi-resource array for vpc/
+  ecs-service/alb). Drop `nfrs` (feeds confidence signal — OOS) and
+  `intra_refs` (feeds wire engine — eliminated by D-012).
+- Confidence: 0.72 *(below threshold — escalate)*
+
+## Environment model
+
+### D-018: `core/environments/dev.json` field set
+- **Default:** Keep `name`, `description`, `account_id`, `region`,
+  `state_backend` (bucket, lock_table), `network` (vpc_cidr, azs).
+  Drop `runner_role_arn` (ABAC OOS), `autonomy` (HITL OOS),
+  `confidence_threshold` (OOS).
+- Confidence: 0.80
+
+### D-019: `environment_check.check()` signature
+- **Default:** Use REQ-05 signature: `check(env_name: str,
+  environments_dir: Path) -> dict`. Raises `EnvironmentNotFoundError`.
+  Drop ref's `(ok, message)` tuple + onboarding prompt printing.
+- Confidence: 0.90
+
+## Shell scripts
+
+### D-020: `run_platform.sh` stages (policy/confidence/outbox dropped)
+- **Default:**
+  - `--check-only` (offline): env_check → validate contract → resolve →
+    adapter compiles → validate output structure → print
+    `=== PLATFORM CHECK OK ===` → exit 0
+  - `--plan-only` (AWS): above + load creds → terraform init → validate
+    → plan → print `=== PLATFORM PLAN OK ===`
+  - default (AWS, apply): above + `terraform apply -auto-approve` →
+    print `=== PLATFORM APPLY OK ===`
+  - `--quiet`: suppresses TF streaming. `--help`: flags.
+- Confidence: 0.85
+
+### D-021: `run_ci.sh` Stage 1 py_compile
+- **Default:** Glob: `python3 -m py_compile $(find core/ adapters/
+  scripts/ -name '*.py')`. No hardcoded file list (no OOS Python files
+  exist).
+- Confidence: 0.82
+
+### D-031: `run_platform.sh` flag set
+- **Default:** Keep only REQ-20's four: `--check-only`, `--plan-only`,
+  `--quiet`, `--help` (+`-h`). Default = apply. Drop `--apply`,
+  `--destroy`, `--local`, `--decommission`, `--deploy-uptime`,
+  `--environment`.
+- Confidence: 0.87
+
+## Terraform / bootstrap
+
+### D-022: Bootstrap DynamoDB table
+- **Default:** Dedicated lock table `nova-tfstate-locks` (S3 backend
+  `lock_table` points to it). NO `nova-outbox` table (outbox OOS). S3
+  state bucket `nova-tfstate-<account>-<region>` with versioning kept.
+- Confidence: 0.78
+
+### D-023: `terraform/platform/main.tf` content
+- **Default:** ONLY shared platform VPC: `aws_vpc.nova_shared`,
+  `aws_subnet.nova_shared` (count=2), IGW, route table, ECS SG, outputs
+  (`vpc_id`, `subnet_ids`, `ecs_security_group_id`). State backend
+  references. Drop Lambda, DynamoDB contracts, KMS, Secrets, SNS,
+  consumer_invoke_policy — all OOS.
+- Confidence: 0.83
+
+### D-024: `terraform/ci-vpc/main.tf` role
+- **Default:** Short-lived test VPC for module lifecycle testing (ref
+  convention preserved). The shared platform VPC lives in
+  `terraform/platform/main.tf` (D-023). REQ-16's description was a
+  mischaracterization.
+- Confidence: 0.86
+
+### D-025: Onboarding static-key alternative
+- **DECISION (human override):** `terraform/onboarding/main.tf` creates
+  an IAM ROLE (not a user) with a trust policy allowing the platform's
+  runner user to assume it (cross-account assume role pattern). No OIDC.
+  `consumer_repo`/`owner_id` vars kept for tagging. README documents
+  this is dev-only static-key (OIDC is production path, OOS for v1.0).
+  The consumer's CI runner assumes this role via `sts assume-role` using
+  the platform runner's static credentials.
+- Confidence: 0.72 → locked by human review at 1.0
+
+### D-026: IAM runner policy scoping
+- **Default:** Static inline policy `terraform/bootstrap/
+  spike_runner_policy.json` scoped to platform account+region, granting
+  Terraform-deployable resource permissions. NOT ABAC-scoped. Account
+  ID parameterized via variable (not hardcoded). Attached to
+  `nova-spike-runner` user by `create_iam_user.py`.
+- Confidence: 0.75
+
+## Python packaging / naming / docs / tests
+
+### D-027: `pyproject.toml` — CLI package or scripts only?
+- **Default:** No CLI package. `pyproject.toml` configures pytest +
+  py_compile + project metadata. No `[project.scripts]`. No `nova/`
+  package dir. Invoked via shell scripts. Python modules run as
+  scripts.
+- Confidence: 0.85
+
+### D-028: `docs/modules/` layout
+- **Default:** `docs/modules/index.md` (catalog table linking to
+  `modules/l1/<name>/README.md` and `modules/l2/<name>/README.md`).
+  Per-module docs live in `modules/`, not `docs/modules/`. Mirrors ref
+  exactly.
+- Confidence: 0.82
+
+### D-029: `modules/STANDARDS.md` + `README-TEMPLATE.md`
+- **Default:** Keep `modules/README.md` (REQ-13, trimmed of
+  security/attestation). Keep `modules/README-TEMPLATE.md` (per-module
+  template). Drop `modules/STANDARDS.md` (673 lines, mostly
+  security/compliance/attestation — OOS).
+- Confidence: 0.75
+
+### D-030: moto usage in tests
+- **Default:** moto pinned in requirements-test.txt (REQ-31) but used
+  minimally. Check-only is offline (no AWS). Most tests are pure
+  (resolver, adapter, schemas). moto kept for future AWS-touching
+  tests. If unused, harmless pinned dep.
+- Confidence: 0.68 *(below threshold — escalate)*
+
+### D-032: `NOVA_*` env var naming
+- **Default:** Keep `NOVA_*` prefix: `NOVA_AWS_ACCESS_KEY_ID`,
+  `NOVA_AWS_SECRET_ACCESS_KEY`, `NOVA_BOOTSTRAP_AWS_*`, `NOVA_FORGE_TOKEN`.
+  `.env.secrets` uses `NOVA_AWS_*` keys. `run_platform.sh` copies
+  `NOVA_AWS_*` to `AWS_*` env vars.
+- Confidence: 0.88
+
+### D-034: Engine-boundary test (REQ-09) file scope
+- **Default:** Scan `.py` files only (in `core/`, `schemas/`,
+  `contracts/`, `tests/`, `scripts/`, root). Exclude `adapters/terraform/`
+  (the boundary), `modules/`, `.tf`, `.md`, `.json` in modules/envs
+  (data files with `terraform_dir` paths — not engine logic).
+- Confidence: 0.83
+
+## Grill fixes (D-037, D-038 — locked from GRILL.md conditions)
+
+### D-037: Resolver-source / engine-boundary / adapter-signature (C-1 fix)
+- **DECISION (human-locked):** Match the reference design. Drop `source`
+  from `stack.schema.json` (REQ-04). Change `adapt(stack, modules_dir)`
+  → `adapt(stack, repo_root)` (REQ-07). The adapter loads `registry.json`
+  internally to map `module` → `terraform_dir` — this happens inside
+  the engine boundary (`adapters/terraform/`), so it's permitted. The
+  resolver never writes Terraform paths into the stack. Stack is
+  engine-agnostic: `{contract_id, contract_name, environment, resources:
+  [{module, version, inputs}]}`. Side effect (C-4): P2 (adapter) gains a
+  dependency on P3-W1 (registry.json) — reorder P3-W1 before P2-W1.
+- Confidence: 1.0 (human-locked grill fix)
+- Alternatives: [keep `source` + relax boundary test (fragile); rename
+  to `module_path` (doesn't fix the substring match)]
+
+### D-038: L2 child set (C-2 fix)
+- **DECISION (human-locked):** Lock the ARCHITECTURE.md compositions as
+  D-036. `microservice` = vpc + ecs-cluster + ecs-service + iam-role +
+  ecr + alb (6 L1s). `static-assets` = s3 + cloudfront + kms-key (3 L1s,
+  drops waf from reference). These are fresh compositions under the
+  opaque L2 model (D-012) — not reference mirrors.
+- Confidence: 1.0 (human-locked grill fix)
+- Alternatives: [match reference children exactly (microservice no
+  vpc, static-assets keeps waf); microservice + kms (7 L1s)]
@@ -0,0 +1,115 @@
+# GRILL — Nova Platform v1.0 (Phase 0)
+
+> Adversarial red-team of the v1.0 plan. 9 axes reviewed against the
+> reference at `/home/opencode/acdl/` + locked decisions.
+
+## Verdict: PROCEED-WITH-CONDITIONS — Confidence 0.82 → PROCEED (all conditions resolved)
+
+One **blocking** architectural contradiction (C-1) + 5 non-binding
+conditions. **All resolved under supervised autonomy:**
+- C-1 (BLOCKING): D-037 locked — adapter loads registry, no `source`
+  in stack. REQ-04 + REQ-07 updated.
+- C-2 (High): D-038 locked — L2 compositions = ARCHITECTURE.md's.
+- C-3 (Medium): AC-8 now mechanically checkable (docs OOS grep).
+- C-4 (Medium): Wave graph reordered — P3-W1 before P2-W1.
+- C-5 (Low): Concurrency note added to PLAN.md.
+- C-6 (Low): "without deviation" → "with 9 locked deviations" in
+  PROJECT.md + PERSONAS.md.
+
+## Binding conditions
+
+### C-1 (BLOCKING) — resolver-source / engine-boundary / adapter-signature contradiction
+
+**The kill shot.** Three locked decisions are mutually unsatisfiable:
+
+| Decision | Requires | Location |
+|----------|----------|----------|
+| REQ-04 + D-012 | Stack resource carries `source` field (Terraform path) | `core/contract_resolver.py` populates it |
+| REQ-09 + D-034 | No `.py` in `core/` may contain `terraform` | `tests/test_engine_boundary.py` greps |
+| REQ-07 | `adapt(stack, modules_dir) -> str` — no registry param | adapter can't resolve `source` |
+
+**Verified against reference:** `acdl/schemas/stack.schema.json` has NO
+`source` field. `acdl/adapters/terraform/adapter.py:19` loads
+`registry.json` itself (`_load_registry`). The reference resolver never
+writes a `terraform_dir` path into the stack. nova-platform's design
+inverts this — putting `source` in the stack (resolver's job) while
+keeping the adapter signature registry-less. The resolver must write
+`"modules/l1/s3/terraform"` (contains forbidden `terraform`) → **AC-5
+ AC-10 will fail.**
+
+**Fix (recommended — matches reference):**
+- Drop `source` from `stack.schema.json` (REQ-04).
+- Change `adapt(stack, modules_dir)` → `adapt(stack, repo_root)` (REQ-07).
+- Adapter loads `registry.json` internally (inside the boundary — it's
+  the engine-specific code, permitted to read `terraform_dir`).
+- L2 `terraform_dir` in registry (D-013) consumed by adapter, not resolver.
+
+**Side effect (C-4):** if adopted, P2 (adapter) gains a dependency on
+P3-W1 (registry.json). Reorder: P3-W1 before P2-W1, or split P3.
+
+### C-2 (High) — L2 child set underspecified
+
+ARCHITECTURE.md:114-115 describes L2 compositions:
+- `microservice = vpc + ecs-cluster + ecs-service + iam-role + ecr + alb`
+- `static-assets = s3 + cloudfront + kms-key`
+
+But the reference `microservice` children = cluster, ecr, roles, alb,
+service, kms (no vpc); `static-assets` = s3, cloudfront, **waf**, kms.
+Nova drops waf from static-assets (consistent — waf L1 kept but not in
+the L2). These are fresh-authored under D-012 (opaque L2), so not a
+reference-mirror violation, but the composition is underspecified — no
+decision locks the L2 child set.
+
+**Fix:** Lock D-036 before P4-W2 specifying exactly which L1 modules
+each L2 composes. Reconcile ARCHITECTURE.md.
+
+### C-3 (Medium) — AC-8 not mechanically checkable
+
+AC-8 ("docs... no OOS sections") is subjective. P6-W3 greps for OOS
+*file names* but not OOS *content* inside allowed docs. A doc could
+contain a "Security" section and pass.
+
+**Fix:** Add grep check for OOS section headings ("Security",
+"Compliance", "OIDC", "Attestation", "ABAC") inside `docs/*.md` +
+`modules/*/README.md`. Make AC-8 mechanically checkable.
+
+### C-4 (Medium) — missing dep if C-1(a) adopted
+
+If C-1's recommended fix is adopted (adapter loads registry), P2 gains
+a dependency on P3-W1 (registry.json). Current graph runs P2 + P3 in
+parallel after P1.
+
+**Fix:** Reorder P3-W1 before P2-W1, or split P3 into "registry first"
+ "L1 terraform second". Update the wave dependency graph.
+
+### C-5 (Low) — concurrency cap violation
+
+PLAN claims "No wave has >5 parallel tasks" but P3-W1 has 13, P3-W2 has
+13, P4-W1 has 8. `max_concurrent_agents=5` → these batch-serialize into
+3-5 rounds, inflating P3 wall-clock ~2-3×.
+
+**Fix:** Either raise the cap for these waves or restate the schedule
+estimate to reflect batching. Non-blocking.
+
+### C-6 (Low) — "without deviation" claim is false
+
+PROJECT.md:11 + PERSONAS.md:17,148 claim "structural conventions
+preserved **without deviation**." RESEARCH.md itself lists **9 locked
+deviations** (D-012, D-013, D-015, D-017, D-018, D-019, D-022, D-023,
+D-025, D-027). An implementer may reject the needed C-1 fix as
+"violating conventions."
+
+**Fix:** Rewrite the claim to "structural conventions preserved except
+the 9 locked deviations in CLARIFY.md."
+
+## Additional notes (non-binding)
+
+- **ARCHITECTURE.md:32 example bug:** `id: my-static-site` (14 chars)
+  fails the locked pattern `^[a-z][a-z0-9-]{2,5}$` (max 6). Fix to
+  `id: stsi` or `id: assets`.
+- **D-014 (0.72), D-017 (0.70), D-030 (0.68):** marked below threshold
+  in CLARIFY.md but D-017/D-030 show no human-lock record (unlike D-025).
+  These WERE escalated + answered in the clarify stage question round —
+  confirmed locked. No action needed.
+- **moto pinned but unused (D-030):** harmless. Keep or drop; not
+  blocking.
@@ -0,0 +1,164 @@
+---
+personas:
+  - name: lead-developer
+    domain: coordination
+    active: true
+    frameworks:
+      - python
+      - bash
+      - terraform
+      - jsonschema
+      - pytest
+      - boto3
+    constraints:
+      - pragmatic
+      - battle-tested defaults
+      - engine-agnostic core
+      - acdl structural conventions preserved with 9 locked deviations (D-012, D-013, D-015, D-017, D-018, D-019, D-022, D-023, D-025, D-027)
+      - no security/identity/CI-workflow (out of scope)
+      - local shell reproducibility over CI
+    territory:
+      - ".ciagent/**"
+      - "README.md"
+      - "pyproject.toml"
+      - "requirements-test.txt"
+      - ".gitignore"
+      - "docs/architecture.md"
+      - "docs/consumer-guide.md"
+  - name: data-engineer
+    domain: data
+    active: true
+    frameworks:
+      - terraform
+      - hcl
+      - jsonschema
+      - json
+    constraints:
+      - schema-first
+      - type-safe
+      - migration-driven
+      - engine terms only in adapters/terraform/ + modules/*/terraform/ + terraform/
+      - module interface shape: {name, version, kind, type, description, inputs, outputs, resources[]}
+      - registry entry shape: {interface, terraform_dir, published_at, deprecated, kind}
+      - L2 is opaque (D-012): interface.json + terraform/main.tf composes L1 internally
+      - state key convention: spike/<stack_name>/<environment>/terraform.tfstate
+      - tag convention: nova:owner/nova:contract/nova:environment/nova:cost-center
+    territory:
+      - "modules/**"
+      - "terraform/**"
+      - "schemas/stack.schema.json"
+      - "schemas/environment.schema.json"
+      - "docs/modules/**"
+      - "docs/environments/**"
+      - "**/*.tf"
+      - "**/*.tf.json"
+  - name: backend-engineer
+    domain: backend
+    active: true
+    frameworks:
+      - python
+      - pyyaml
+      - jsonschema
+      - boto3
+      - pytest
+      - moto
+      - bash
+    constraints:
+      - api-first
+      - strict-typing
+      - dependency-injection
+      - engine-agnostic core (no aws_*/terraform/module "/provider "/resource " strings outside adapters/terraform/)
+      - resolve() is pure: no network/side-effects; local file reads for module metadata permitted (D-011)
+      - adapt() is a stateless assembler: no terraform invocation, no state files, no plan files
+      - named exceptions: ModuleNotFoundError, VersionNotFoundError, EnvironmentNotFoundError
+      - NOVA_* env var prefix (D-032): NOVA_AWS_* -> AWS_* copy in run_platform.sh
+      - no CLI package (D-027): scripts invoked via shell
+    territory:
+      - "core/**"
+      - "adapters/terraform/adapter.py"
+      - "adapters/terraform/__init__.py"
+      - "schemas/contract.schema.json"
+      - "contracts/**"
+      - "scripts/**"
+      - "tests/**"
+      - "**/*.py"
+  - name: frontend-engineer
+    domain: frontend
+    active: false
+    frameworks:
+      - react
+      - next.js
+    constraints:
+      - component-first
+      - server-components
+      - minimal-client-js
+    territory:
+      - "**/components/**"
+      - "**/pages/**"
+      - "**/hooks/**"
+      - "**/styles/**"
+      - "**/*.tsx"
+      - "**/*.css"
+      - "**/*.vue"
+    reason: Nova Platform has no frontend. Deactivated (D-006).
+phase_personas: []
+---
+
+# Personas — Nova Platform v1.0
+
+> Active personas for all execution phases. The 3 active personas cover
+> the full v1.0 scope (contract surface + resolution + engine adapter +
+> module catalog + Terraform bootstrap + shell reproducibility + tests +
+> docs). No phase-specific personas are needed.
+
+## Roster
+
+| Persona | Domain | Active | Lead coverage |
+|---------|--------|--------|---------------|
+| lead-developer | coordination | yes | cross-cutting: `.ciagent/`, root config, architecture docs |
+| data-engineer | data (terraform/modules) | yes | `modules/`, `terraform/`, stack/environment schemas, module docs |
+| backend-engineer | backend (python) | yes | `core/`, `adapters/terraform/*.py`, contract schema, `contracts/`, `scripts/`, `tests/` |
+| frontend-engineer | frontend | NO (D-006) | — |
+
+## Framework alignment
+
+The project has NO JavaScript/frontend runtime. Frameworks overridden
+from config.json defaults to match actual project deps:
+
+- **lead-developer:** python, bash, terraform, jsonschema, pytest, boto3.
+- **data-engineer:** terraform, hcl, jsonschema, json (was `["terraform"]` — expanded; dropped nothing).
+- **backend-engineer:** python, pyyaml, jsonschema, boto3, pytest, moto, bash (was `["python", "fastapi"]` — **dropped `fastapi`** (no HTTP API; shell-invoked); added actual deps).
+- **frontend-engineer:** unchanged (deactivated).
+
+## Territory alignment
+
+Territory globs overridden to match actual file structure. The
+reference's `nova/`, `pipelines/`, `metrics/`, `.github/workflows/`,
+`mcp/`, `skills/`, `workflows-src/`, `platform/` dirs do NOT exist.
+
+- **lead-developer:** `.ciagent/**`, `README.md`, `pyproject.toml`, `requirements-test.txt`, `.gitignore`, `docs/architecture.md`, `docs/consumer-guide.md`.
+- **data-engineer:** `modules/**`, `terraform/**`, `schemas/stack.schema.json`, `schemas/environment.schema.json`, `docs/modules/**`, `docs/environments/**`, `**/*.tf`, `**/*.tf.json`. NOTE: `schemas/contract.schema.json` is backend-engineer territory.
+- **backend-engineer:** `core/**`, `adapters/terraform/adapter.py`, `adapters/terraform/__init__.py`, `schemas/contract.schema.json`, `contracts/**`, `scripts/**`, `tests/**`, `**/*.py`. NOTE: `adapters/terraform/policy/` is OOS.
+- **frontend-engineer:** unchanged (deactivated).
+
+## Constraint alignment
+
+### Shared constraints (all active personas)
+- **engine-agnostic core:** no `aws_*` / `terraform` / `module "` / `provider "` / `resource "` strings outside `adapters/terraform/` (verified by `tests/test_engine_boundary.py`).
+- **acdl structural conventions preserved with 9 locked deviations:** directory names, file roles, module interface shape, registry format, banner strings, state key convention, tag convention. Deviations locked in CLARIFY.md (D-012, D-013, D-015, D-017, D-018, D-019, D-022, D-023, D-025, D-027).
+- **no security/identity/CI-workflow:** kyverno, Wiz, Checkov, PolicyEngine, confidence_signal, outbox_writer, ABAC, PAT, JWS, KMS signing, SoD, HITL, attestation, submission_readiness, env_transition, decommission, mode_resolver, onboarding flow beyond bootstrap, metrics, pipelines, `.github/workflows/` — ALL out of scope. Do NOT implement.
+
+### Persona-specific constraints
+- **lead-developer:** pragmatic, battle-tested defaults, engine-agnostic core, acdl structural conventions, no security/identity/CI-workflow, local shell reproducibility over CI.
+- **data-engineer:** schema-first, type-safe, migration-driven, engine terms only in `adapters/terraform/` + `modules/*/terraform/` + `terraform/`, module interface shape, registry entry shape, L2 opaque per D-012, state key `spike/<stack_name>/<environment>/terraform.tfstate`, tag convention.
+- **backend-engineer:** api-first (contract schema is the API), strict-typing, dependency-injection, `resolve()` pure (D-011), `adapt()` stateless assembler, named exceptions, `NOVA_*` env prefix (D-032), no CLI package (D-027).
+
+## Phase-specific personas
+
+None. The 3 active personas cover all 6 execution phases:
+- Phase 1 (Contract Surface + Schemas + Resolver): backend-engineer.
+- Phase 2 (Terraform Adapter + Engine Boundary): backend-engineer.
+- Phase 3 (L1 Primitives + Registry): data-engineer (registry + interfaces + terraform), backend-engineer (registry-loading code).
+- Phase 4 (L2 Patterns + Terraform Bootstrap + Platform): data-engineer (L2 terraform, bootstrap terraform, platform/ci-vpc/microservice/onboarding terraform), backend-engineer (bootstrap python scripts).
+- Phase 5 (Shell Reproducibility + Test Suite + Docs): backend-engineer (scripts, tests), lead-developer (README, docs, pyproject), data-engineer (docs/modules, docs/environments).
+- Phase 6 (Final Review + Ship): lead-developer.
@@ -0,0 +1,410 @@
+# PLAN — Nova Platform v1.0
+
+> Task-level, wave-ordered, persona-assigned plan for the 5 execution
+> phases (P1..P5) + the final phase (P6). Consumed by the execute
+> workflow. Derived from ROADMAP.md phase breakdown + REQUIREMENTS.md
+> REQ coverage + PERSONAS.md assignments + CLARIFY.md D-011..D-035 +
+> RESEARCH.md reference shapes.
+
+## User-Facing Surface
+
+The platform's user-facing surfaces are **entirely offline-runnable** —
+no CI required, no AWS credentials required for the primary verification
+path:
+
+1. **`scripts/run_platform.sh --check-only`** — Offline validation
+   entrypoint. `bash scripts/run_platform.sh --check-only
+   contracts/static-assets.yml` → exit 0 + `=== PLATFORM CHECK OK ===`
+   iff contract validates → resolves → stack is schema-valid → adapter
+   compiles to structurally-valid HCL. No AWS calls.
+2. **`scripts/run_platform.sh`** (default mode) — Full apply path.
+   Loads `NOVA_AWS_*` → `AWS_*`, runs terraform init/validate/plan/apply,
+   prints `=== PLATFORM APPLY OK ===`. `--plan-only` stops before apply.
+3. **`scripts/run_ci.sh`** — Local CI mirror. lint (py_compile) → test
+   (pytest) → check-only. Prints `=== CI PIPELINE OK ===`.
+4. **`docs/consumer-guide.md`** — Consumer happy-path walkthrough.
+5. **`README.md`** quickstart — operator/dev quickstart.
+6. **`.feature`-equivalent scenarios** — `tests/test_run_platform_check_only.py`
+   + `tests/test_run_ci.py` encode the happy path as executable pytest cases.
+
+## Happy Path
+
+Two end-to-end scenarios, written BEFORE execute, verified by automated
+tests in P5:
+
+### Scenario A — Offline contract validation (primary gate)
+
+```bash
+bash scripts/run_platform.sh --check-only contracts/static-assets.yml
+# expected: === PLATFORM CHECK OK === ; exit 0
+```
+
+Steps: load `core/environments/dev.json` → parse contract → validate
+against contract schema → resolve to stack (interpolation) → adapt to
+HCL → validate output structure → print banner → exit 0. No AWS SDK
+calls, no terraform binary, no network.
+
+### Scenario B — Local CI mirror
+
+```bash
+bash scripts/run_ci.sh
+# expected: === CI PIPELINE OK === ; exit 0
+```
+
+Steps: (1) lint `py_compile $(find core/ adapters/ scripts/ -name '*.py')`;
+(2) test `pytest`; (3) check-only `run_platform.sh --check-only`. Print
+banner → exit 0.
+
+## UX Acceptance Criteria
+
+v1.0 is accepted iff ALL hold:
+
+1. **AC-1 (offline validation works):** `run_platform.sh --check-only
+   contracts/static-assets.yml` exits 0 + stdout contains
+   `=== PLATFORM CHECK OK ===`. (tests/test_run_platform_check_only.py)
+2. **AC-2 (local CI works):** `run_ci.sh` exits 0 + stdout contains
+   `=== CI PIPELINE OK ===`. (tests/test_run_ci.py)
+3. **AC-3 (contract schema is the API):** all 10 sample contracts
+   validate against contract.schema.json. (tests/test_contract_schema.py)
+4. **AC-4 (resolver pure + correct):** `resolve()` returns stack
+   validating against stack.schema.json; raises `ModuleNotFoundError`/
+   `VersionNotFoundError`. (tests/test_contract_resolver.py +
+   test_stack_schema.py)
+5. **AC-5 (adapter compiles + boundary holds):** `adapt(stack, repo_root)` (C-1 fix)
+   emits valid HCL; no `.py` outside `adapters/terraform/` contains
+   forbidden strings. (tests/test_terraform_adapter.py + test_engine_boundary.py)
+6. **AC-6 (module catalog complete):** registry.json has 13 L1 + 2 L2 =
+   15 entries; all interface.json + terraform/main.tf exist; L2 entries
+   include `terraform_dir` (D-013).
+7. **AC-7 (Terraform roots + bootstrap exist):** terraform/{bootstrap,
+   ci-vpc,platform,microservice,onboarding}/ per REQ-14..19 + D-022..D-025.
+   Lock table `nova-tfstate-locks`; account parameterized.
+8. **AC-8 (docs cover consumer journey):** README + docs/{architecture,
+   consumer-guide,modules/index,environments/index,contracts/index}.md
+   exist, no OOS sections. Mechanically checked by grep for OOS section
+   headings ("Security", "Compliance", "OIDC", "Attestation", "ABAC")
+   inside `docs/*.md` + `modules/*/README.md` — zero matches (C-3 fix).
+9. **AC-9 (reproducibility):** requirements-test.txt pins 5 deps;
+   pyproject.toml no `[project.scripts]`; rotate_spike_key.sh writes
+   .env.secrets (0600); .gitignore covers .env*/terraform state.
+10. **AC-10 (engine-agnostic invariant):** engine-boundary test passes.
+
+---
+
+## Phase 1 — Contract Surface + Schemas + Resolver
+
+**Goal:** A contract can be validated, resolved to a stack, environment
+checked, stack validated — all offline, no apply, no engine terms in
+contract/core layer.
+
+**REQs:** REQ-01, REQ-02, REQ-03, REQ-04, REQ-05, REQ-06, REQ-23,
+REQ-24, REQ-27, REQ-28.
+
+**Personas:** backend-engineer (contract schema, resolver,
+environment_check, contracts, tests); data-engineer (stack schema,
+environment schema, dev.json).
+
+**Ships as:** `v0.1.1` on `phase/01-contract-surface-schemas-resolver`.
+
+### Wave 1 (parallel — schemas + env data)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P1-W1-T1 | backend | REQ-01, D-015 | `schemas/contract.schema.json` | Draft 2020-12; `required:[id,name,environment,infrastructure]`; `id` pattern `^[a-z][a-z0-9-]{2,5}$`; `infrastructure` ARRAY (D-015) items `{module,version?,inputs}`; no engine terms. |
+| P1-W1-T2 | data | REQ-04, D-012 | `schemas/stack.schema.json` | Flat per D-012; `required:[contract_id,contract_name,environment,resources]`; resources `{module,version,source,inputs}`; no stack wrapper/relationships/nfrs. |
+| P1-W1-T3 | data | D-017, D-018 | `schemas/environment.schema.json` | `required:[name,account_id,region,state_backend,network]`; no runner_role_arn/autonomy/confidence_threshold; `additionalProperties:false`. |
+| P1-W1-T4 | data | REQ-06, D-018 | `core/environments/dev.json` | Validates against environment schema; `name:"dev"`, placeholder account, `us-east-1`, state_backend, network. |
+
+### Wave 2 (resolver + env_check — depends on W1)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P1-W2-T1 | backend | REQ-03, D-011, D-016, D-037 | `core/contract_resolver.py` | `resolve(contract, registry, modules_dir) -> dict` (D-011). Interpolation kept (D-016). Named exceptions `ModuleNotFoundError`/`VersionNotFoundError`. L2 opaque (D-012). **No `source` in stack (D-037/C-1 fix) — stack is engine-agnostic `{contract_id, contract_name, environment, resources:[{module,version,inputs}]}`.** No engine terms. |
+| P1-W2-T2 | backend | REQ-05, D-019 | `core/environment_check.py` | `check(env_name, environments_dir) -> dict` (D-019). Raises `EnvironmentNotFoundError`. No tuple/onboarding_message/CLI. No engine terms. |
+
+### Wave 3 (sample contracts — depends on W1+W2)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P1-W3-T1 | backend | REQ-02, D-033, D-035 | `contracts/static-assets.{yaml,dev.yml,qa.yml,prod.yml,dr.yml}` | Validate against contract schema; `static-assets` L2; inputs incl `bucket_name`/`index_document` (D-035); per-env differ only in `environment` (D-033); interpolation tokens. |
+| P1-W3-T2 | backend | REQ-02, D-033 | `contracts/microservice.{yaml,dev.yml,qa.yml,prod.yml,dr.yml}` | Validate; `microservice` L2; per-env differ only in `environment`; interpolation. |
+
+### Wave 4 (parallel — tests, depends on W1-W3)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P1-W4-T1 | backend | REQ-23 | `tests/test_contract_resolver.py` | Happy path, `ModuleNotFoundError`, `VersionNotFoundError`, empty infra. Pass. |
+| P1-W4-T2 | backend | REQ-24 | `tests/test_environment_check.py` | `check("dev",...)` returns dict; missing → `EnvironmentNotFoundError`; malformed. Pass. |
+| P1-W4-T3 | backend | REQ-27 | `tests/test_contract_schema.py` | All 10 contracts validate; negative cases raise. Pass. |
+| P1-W4-T4 | backend | REQ-28 | `tests/test_stack_schema.py` | `resolve()` stack validates; negative cases. Pass. |
+
+### Must-haves
+- 3 schemas parse as valid JSON Schema draft 2020-12.
+- `resolve()` + `check()` exposed with named exceptions; no engine terms.
+- `dev.json` + 10 contracts validate.
+- `pytest -q tests/test_contract_resolver.py tests/test_environment_check.py tests/test_contract_schema.py tests/test_stack_schema.py` exit 0.
+
+---
+
+## Phase 2 — Terraform Adapter + Engine Boundary
+
+**Goal:** A resolved stack compiles to valid HCL via the stateless
+adapter; engine boundary enforced by grep test.
+
+**REQs:** REQ-07, REQ-08, REQ-09, REQ-25, REQ-26.
+
+**Personas:** backend-engineer (adapter + tests).
+
+**Ships as:** `v0.1.2` on `phase/02-terraform-adapter-engine-boundary`.
+
+> **Dependency (C-4 fix):** P2 depends on P3-W1 (registry.json). The
+> adapter loads `registry.json` internally (C-1 fix). Reorder: run
+> P3-W1 (registry.json only) before P2-W1, then continue P3-W2 (L1
+> terraform dirs) in parallel with P2.
+
+### Wave 1 (adapter — depends on P3-W1 registry.json)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P2-W1-T1 | backend | REQ-07, REQ-08, D-013, D-037 | `adapters/terraform/adapter.py`, `adapters/terraform/__init__.py` | `adapt(stack, repo_root) -> str` (C-1/D-037 fix). Loads `modules/registry.json` internally to map `module` → `terraform_dir`. Stateless, <250 lines. Emits `module "x" { source; <inputs> }` per resource. L2 `terraform_dir` from registry (D-013). `__init__.py` re-exports. ONLY place engine terms appear. |
+
+### Wave 2 (parallel — tests)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P2-W2-T1 | backend | REQ-25 | `tests/test_terraform_adapter.py` | Single/multi resource, input passthrough, HCL validity. Pass. |
+| P2-W2-T2 | backend | REQ-09, REQ-26, D-034 | `tests/test_engine_boundary.py` | Grep `.py` in core/schemas/contracts/tests/scripts/root; exclude adapters/terraform/ + modules/ + .tf/.md/.json; zero matches for forbidden strings. Pass. |
+
+### Must-haves
+- `adapt()` stateless, <250 lines, returns HCL.
+- `__init__.py` re-exports.
+- Both tests pass; boundary proven.
+
+---
+
+## Phase 3 — L1 Primitives + Registry
+
+**Goal:** Full module catalog — registry.json indexing 13 L1 + 2 L2,
+each L1 with interface.json + terraform/ (main/variables/outputs/versions/locals).
+
+**REQs:** REQ-10, REQ-11, REQ-13.
+
+**Personas:** data-engineer (registry, 13 L1 interface.json + terraform,
+READMEs, docs/modules/index); backend-engineer (registry test, conftest).
+
+**Ships as:** `v0.1.3` on `phase/03-l1-primitives-registry`.
+
+### Wave 1 (parallel — registry + 13 L1 interface.json + READMEs + docs index)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P3-W1-T1 | data | REQ-10, D-013 | `modules/registry.json` | 15 entries; L1 `{interface,terraform_dir,published_at,deprecated,kind:"l1"}`; L2 includes `terraform_dir` (D-013). |
+| P3-W1-T2..T14 | data | REQ-11, D-014 | `modules/l1/{s3,vpc,ecs-cluster,ecs-service,iam-role,alb,ecr,cloudfront,waf,rds,kms-key,dynamodb,uptime}/interface.json` | `{name,version,kind:"l1",type,description,inputs,outputs}` + `resources[]` for multi-resource. No `nfrs`/`intra_refs` (D-014). s3 stays ref interface (D-035). |
+| P3-W1-T15 | data | REQ-13, D-029 | `modules/README.md`, `modules/README-TEMPLATE.md` | L1/L2 distinction, registry format, add-a-module. 13+2 tables. Trimmed of security/compliance. DROP NFRs + Compliance sections. No STANDARDS.md. |
+| P3-W1-T16 | data | REQ-34, D-028 | `docs/modules/index.md` | Catalog table → links to `modules/l1/<name>/README.md` + `modules/l2/<name>/README.md`. 15 rows. |
+
+### Wave 2 (parallel — 13 L1 terraform/ dirs)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P3-W2-T1..T13 | data | REQ-11 | `modules/l1/<name>/terraform/{main,variables,outputs,versions,locals}.tf` | `count = var.enabled ? 1 : 0`; `required_version = ">= 1.9, < 1.10"`; `aws ~> 5.0`; variables match interface.json inputs. |
+
+### Wave 3 (registry test + conftest)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P3-W3-T1 | backend | REQ-10 | `tests/test_registry.py` | 15 entries, L2 has `terraform_dir`, interface paths resolve, terraform_dir/main.tf exist. Pass. |
+| P3-W3-T2 | backend | (support) | `tests/conftest.py` (partial) | `repo_root` + `registry` fixtures. No `stack_instance`/`policy_check_result_schema`. |
+
+### Must-haves
+- registry.json valid, 15 entries, L2 has `terraform_dir`.
+- 13 L1 interface.json + terraform dirs exist, conform to D-014.
+- READMEs trimmed; docs/modules/index links to all 15.
+- test_registry.py + conftest fixtures pass.
+
+---
+
+## Phase 4 — L2 Patterns + Terraform Bootstrap + Platform
+
+**Goal:** Two L2 patterns composing L1 internally; AWS bootstrap
+scripted; platform/ci-vpc/microservice/onboarding roots exist.
+
+**REQs:** REQ-12, REQ-14, REQ-15, REQ-16, REQ-17, REQ-18, REQ-19.
+
+**Personas:** data-engineer (L2 interfaces + terraform, bootstrap
+policy + README, 4 terraform roots); backend-engineer (bootstrap py
+scripts, rotate_spike_key.sh).
+
+**Ships as:** `v0.1.4` on `phase/04-l2-patterns-bootstrap-platform`.
+
+### Wave 1 (parallel — L2 interfaces + bootstrap policy + 4 roots + README)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P4-W1-T1 | data | REQ-12, D-012, D-013 | `modules/l2/microservice/interface.json` | `{name,version,kind:"l2",description,inputs,outputs}` — L2-level only, no children/wires. |
+| P4-W1-T2 | data | REQ-12, D-012, D-035 | `modules/l2/static-assets/interface.json` | Inputs incl `bucket_name`/`index_document` (D-035). |
+| P4-W1-T3 | data | REQ-15, D-026 | `terraform/bootstrap/spike_runner_policy.json` | Account parameterized (NOT hardcoded). Grants S3/DynamoDB lock/ECS/ECR/ELB/IAM/EC2/CloudFront/WAF/KMS. DROP Lambda/Secrets/SNS/CostExplorer/OIDC. |
+| P4-W1-T4 | data | REQ-16, D-024 | `terraform/ci-vpc/main.tf` | Short-lived test VPC; VPC+2 subnets+IGW+route table+ECS SG+cluster; 4 outputs; state key `spike/ci-vpc/terraform.tfstate`. |
+| P4-W1-T5 | data | REQ-17, D-023 | `terraform/platform/main.tf` | ONLY shared VPC per D-023; VPC+2 subnets+IGW+route table+ECS SG; outputs `vpc_id`/`subnet_ids`/`ecs_security_group_id`. DROP Lambda/DynamoDB/KMS/Secrets/SNS. |
+| P4-W1-T6 | data | REQ-18 | `terraform/microservice/main.tf` | Instantiates L2 module + `data.terraform_remote_state` to platform VPC. State key `spike/microservice/<env>/terraform.tfstate`. |
+| P4-W1-T7 | data | REQ-19, D-025 | `terraform/onboarding/main.tf` | IAM ROLE (not user) per D-025. Cross-account `sts:AssumeRole`. NO OIDC. `consumer_repo`/`owner_id` vars. DROP `lambda:InvokeFunctionUrl`. Outputs role arn/name. |
+| P4-W1-T8 | data | REQ-14, D-022 | `terraform/bootstrap/README.md` | Documents `nova-tfstate-locks` (D-022 — NOT `nova-outbox`), `nova-spike-runner`, parameterized account, `NOVA_BOOTSTRAP_AWS_*`. |
+
+### Wave 2 (parallel — 2 L2 terraform composing L1, depends on W1 + P3)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P4-W2-T1 | data | REQ-12, D-012, D-038 | `modules/l2/microservice/terraform/{main,variables,outputs,versions}.tf` | `module "vpc"{source="../../l1/vpc/terraform"}` + cluster/service/role/ecr/alb (6 L1s per D-038). Variables match L2 interface. |
+| P4-W2-T2 | data | REQ-12, D-012, D-035, D-038 | `modules/l2/static-assets/terraform/{main,variables,outputs,versions}.tf` | `module "s3"{source="../../l1/s3/terraform"}` + cloudfront + kms (3 L1s per D-038, drops waf). `index_document` → s3 website. |
+
+### Wave 3 (parallel — bootstrap py scripts + rotate, depends on W1 policy)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P4-W3-T1 | backend | REQ-14, D-022 | `terraform/bootstrap/create_state_backend.py` | S3 `nova-tfstate-<account>-<region>` + DynamoDB `nova-tfstate-locks`. Idempotent. `NOVA_BOOTSTRAP_AWS_*`→`NOVA_AWS_*`→`AWS_*`. `py_compile` clean. No engine-boundary violation (boto3, not HCL). |
+| P4-W3-T2 | backend | REQ-15, D-026 | `terraform/bootstrap/create_iam_user.py` | `nova-spike-runner` + policy + key. Prints `NOVA_AWS_*`. Idempotent. `py_compile` clean. No HCL strings. |
+| P4-W3-T3 | backend | REQ-22, D-032 | `scripts/rotate_spike_key.sh` | Rotates key → `.env.secrets` (0600). `NOVA_AWS_*` (D-032). `bash -n` clean. |
+
+### Must-haves
+- Both L2 interface.json + terraform exist; compose L1 via `module` blocks with `../../l1/...`.
+- bootstrap/ has 4 files; policy account-parameterized; lock table `nova-tfstate-locks`.
+- 4 terraform roots exist per D-023/D-024/D-025.
+- rotate_spike_key.sh syntax-valid.
+- Bootstrap py `py_compile` clean, no engine-boundary violation.
+
+---
+
+## Phase 5 — Shell Reproducibility + Test Suite + Docs
+
+**Goal:** Platform fully reproducible from shell — `run_platform.sh
+--check-only` + `run_ci.sh` exit 0 with banners; full test suite
+passes; docs complete. Happy path green.
+
+**REQs:** REQ-20, REQ-21, REQ-22 (verify), REQ-29, REQ-30, REQ-31,
+REQ-32, REQ-33, REQ-34, REQ-35, REQ-36, REQ-37, REQ-38.
+
+**Personas:** backend-engineer (shell scripts, shell tests, conftest
+final, pyproject, requirements); lead-developer (README, architecture,
+consumer-guide); data-engineer (docs/modules/index finalize,
+environments/index, contracts/index).
+
+**Ships as:** `v0.1.5` on `phase/05-shell-reproducibility-tests-docs`.
+
+### Wave 1 (parallel — scripts + deps + docs)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P5-W1-T1 | backend | REQ-20, D-020, D-031, D-032 | `scripts/run_platform.sh` | Flags: `--check-only`/`--plan-only`/`--quiet`/`--help`. check-only: env_check→validate→resolve→adapter→validate output→`=== PLATFORM CHECK OK ===`. plan-only: +creds (`NOVA_AWS_*`→`AWS_*` then unset)→init/validate/plan→`=== PLATFORM PLAN OK ===`. default: +apply→`=== PLATFORM APPLY OK ===`. `bash -n` clean. check-only exits 0 offline. |
+| P5-W1-T2 | backend | REQ-21, D-021 | `scripts/run_ci.sh` | 3 stages: lint (glob py_compile)→test (pytest)→check-only. `=== CI PIPELINE OK ===`. `--quiet`. `bash -n` clean. |
+| P5-W1-T3 | backend | REQ-31, D-027 | `pyproject.toml`, `requirements-test.txt` | No `[project.scripts]`, no `nova/` dir. 5 test deps. `addopts="-v --tb=short"`. `markers=[offline,slow]`. packages.find: `core,core.*,adapters.*`. |
+| P5-W1-T4 | backend | REQ-38 | `.gitignore` | Verify/extend: `.env*`, terraform state, credentials, `__pycache__/`, `.ciagent/logs/`, `nova_platform.egg-info/`. |
+| P5-W1-T5 | lead | REQ-32 | `README.md` | What platform is, run offline, run tests, run against AWS, repo layout, credentials (static-key only), consumer-guide pointer. No security/identity sections. |
+| P5-W1-T6 | lead | REQ-33 | `docs/architecture.md` | Mirrors `.ciagent/ARCHITECTURE.md`. 4 layers + boundary + OOS list + catalog. No cross-cutting sections. |
+| P5-W1-T7 | lead | REQ-37 | `docs/consumer-guide.md` | Infra-only: create repo, write contract, run check-only, run against AWS. Interpolation table. DROP OIDC/reusable-workflow/decommission/compliance. |
+| P5-W1-T8 | data | REQ-34, D-028 | `docs/modules/index.md` (finalize) | Catalog table → 15 module READMEs. |
+| P5-W1-T9 | data | REQ-36, D-018 | `docs/environments/index.md` | Env model: account/network/state backend — NO IAM/ABAC. Autonomy table: dev autonomous; qa/prod/dr manual. No HITL gates. |
+| P5-W1-T10 | data | REQ-35, D-033 | `docs/contracts/index.md` | Array-based infrastructure schema (D-015) + samples + per-env variants (D-033). Interpolation table. |
+
+### Wave 2 (parallel — shell tests + conftest, depends on W1)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P5-W2-T1 | backend | REQ-29 | `tests/test_run_platform_check_only.py` | `subprocess` `run_platform.sh --check-only contracts/static-assets.yml`; assert exit 0 + `=== PLATFORM CHECK OK ===`. Pass. |
+| P5-W2-T2 | backend | REQ-30 | `tests/test_run_ci.py` | `subprocess` `run_ci.sh`; assert exit 0 + `=== CI PIPELINE OK ===`. Pass. |
+| P5-W2-T3 | backend | (support) | `tests/conftest.py` (finalize) | `repo_root`, `registry`, `stack_schema`, `contract_schema` fixtures. `sys.path.insert` for core/ + adapters/. |
+
+### Wave 3 (full-suite green — depends on W1-W2)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P5-W3-T1 | backend | (gate) | none | `pytest -q` all pass. `bash scripts/run_ci.sh` exit 0 + banner. |
+
+### Must-haves (MVP/UX gate)
+- `run_platform.sh --check-only contracts/static-assets.yml` exit 0 + `=== PLATFORM CHECK OK ===`.
+- `run_ci.sh` exit 0 + `=== CI PIPELINE OK ===`.
+- Full `pytest` suite passes.
+- pyproject + requirements configure pytest/py_compile, no CLI.
+- .gitignore covers all patterns.
+- 6 docs exist, no OOS sections.
+
+---
+
+## Phase 6 — Final Review + Ship
+
+**Goal:** Review v1.0 against AC-1..AC-10, audit for boundary leaks +
+OOS-creep, ship: merge `phase/06`→`milestone/v1.0-nova-platform`→`main`,
+tag `v1.0.0` (major — initial release per D-001), Gitea release, delete
+branches.
+
+**REQs:** none new.
+
+**Personas:** lead-developer (review, audit, ship); backend/data
+consulted for fix-forward.
+
+**Ships as:** `v1.0.0` (major tag).
+
+### Wave 1 (review)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P6-W1-T1 | lead | AC-1..AC-10 | none | Walk all 10 ACs. Record pass/fail. All must PASS before proceeding. Escalate on failure (supervised). |
+
+### Wave 2 (fix-forward, conditional)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P6-W2-T1..Tn | backend/data | (varies) | (varies) | Fix specific AC failures. Re-verify. Max 2 revision iterations. |
+
+### Wave 3 (audit)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P6-W3-T1 | lead | REQ-09, OOS list | none | (1) `pytest -q tests/test_engine_boundary.py` pass. (2) Grep repo for OOS file names (policy_engine, confidence_signal, outbox_writer, abac_*, pat_*, jws_*, kms_signing, hitl_*, attestation_*, separation_*, submission_*, env_transition, decommission_*, mode_resolver, onboarding.py, regression_verify*, metrics/, pipelines/, .github/workflows/, adapters/kyverno-json, adapters/wiz, adapters/checkov, schemas/pipeline*, schemas/deploy-pipeline*, schemas/policy_check_result*, schemas/metrics_*). ZERO matches. (3) No STANDARDS.md, no PPTX/marp. |
+
+### Wave 4 (ship)
+
+| Task | Persona | REQs | Files | Must-have |
+|------|---------|------|-------|-----------|
+| P6-W4-T1 | lead | D-001, D-009 | git refs | Merge `phase/06-final-review-ship`→`milestone/v1.0-nova-platform`. Merge milestone→`main`. Tag `v1.0.0` on main. **`confirm_before_ship=true` per D-009 — escalate before tagging.** Gitea release via `NOVA_FORGE_TOKEN`. Delete phase/0*+1* branches. Verify tag + release URL. |
+
+### Must-haves
+- All 10 ACs PASS.
+- Engine boundary passes; zero OOS files.
+- `v1.0.0` tag on main.
+- Gitea release `v1.0.0` created.
+- All phase branches deleted.
+
+---
+
+## Cross-phase invariants (hold after EVERY phase)
+
+1. **Engine boundary:** no `.py` outside `adapters/terraform/` contains
+   `aws_`/`module "`/`terraform`/`provider "`/`resource "` (REQ-09/D-034).
+2. **No OOS-creep:** no file from PROJECT.md/REQUIREMENTS.md OOS list
+   created in any phase.
+3. **Structural conventions:** directory names, file roles, interface
+   shape, registry shape, banner strings, state key, tag convention
+   preserved without deviation.
+4. **Tests stay green:** once a test file exists, subsequent phases must
+   not break it. `pytest -q` passes at end of every phase.
+5. **Supervised escalation:** `ship` (P6-W4-T1) + verification failures
+   escalate to human per `escalation_timeout_ms=300000`.
+
+## Wave dependency graph
+
+```
+P1: W1(schemas+env) → W2(resolver+env_check) → W3(contracts) → W4(tests)
+P3-W1(registry.json ONLY) → P2: W1(adapter loads registry) → W2(adapter tests + boundary)  [C-4 fix: P3-W1 before P2-W1]
+P3: W1(registry+13 L1 interface+READMEs+docs) → W2(13 L1 terraform) → W3(registry test+conftest)  [W1 split: registry.json first, then rest]
+P4: W1(L2 interfaces+bootstrap policy+4 roots+README) → W2(2 L2 terraform per D-038) → W3(2 bootstrap py+rotate)  [deps P3 L1 terraform]
+P5: W1(2 scripts+pyproject+reqs+gitignore+README+arch+consumer-guide+3 docs) → W2(2 shell tests+conftest) → W3(full-suite green)  [deps P1-P4]
+P6: W1(review AC-1..10) → [W2 fix-forward] → W3(audit + docs OOS grep C-3) → W4(ship v1.0.0)  [deps P5]
+```
+
+> **Concurrency note (C-5):** P3-W1 (13 L1 interface.json tasks) +
+> P3-W2 (13 L1 terraform tasks) + P4-W1 (8 tasks) exceed
+> `max_concurrent_agents=5`. These waves batch-serialize into 3-5
+> rounds. Schedule estimate reflects ~2-3× wall-clock for P3.
+
+Total: 6 phases, ~45 tasks across ~13 waves, 3 active personas (max
+concurrency 5). No wave has >5 parallel tasks.
@@ -0,0 +1,98 @@
+# Nova Platform — Infrastructure Delivery
+
+> **Derived from** the Nova reference (`acdl`) — a simplified,
+> infrastructure-only platform. The DevSecOps, security-scoring,
+> identity/ABAC, audit-ledger, and central CI-pipeline-contract machinery
+> of the reference are intentionally **removed**. What remains is the
+> infrastructure-delivery core: a consumer declares intent via a YAML
+> contract; the platform resolves it to a stack, compiles it through the
+> Terraform adapter, and applies it. Structural conventions (directory
+> names, file roles, module interface shape, registry format) are
+> preserved with 9 locked deviations (D-012, D-013, D-015, D-017,
+> D-018, D-019, D-022, D-023, D-025, D-027 — see CLARIFY.md) from the
+> reference.
+
+## Vision / Core Value
+
+Consumers declare infrastructure intent; the platform delivers it. The
+platform absorbs one friction: the cognitive load of getting the
+infrastructure right. 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. There is no security scoring, no audit chain, no identity layer, and
+no reusable CI workflow — those are explicitly out of scope.
+
+Source of truth for **how**: `docs/architecture.md` +
+`.ciagent/ARCHITECTURE.md`. Where the two conflict, ARCHITECTURE.md wins.
+
+## North Star
+
+A merged change progresses through lower environments without a platform
+engineer authoring a workflow, a configuration file, or a Terraform
+module. A consumer declares infrastructure and the platform applies it.
+Every deployment is reproducible from the shell, not just in CI.
+
+## Core Tenets
+
+1. **Operations are Declared, Not Executed.** Consumers define what
+   they need; the platform reconciles, provisions, and applies.
+2. **The Delivery Lifecycle is a Sovereign Boundary.** The platform
+   governs infrastructure only; it does not reach into upstream product
+   / SDLC. Integration is only through the validated contract boundary.
+3. **Dev is Autonomous; Higher Environments are Manual.** Dev applies
+   autonomously. QA/prod/dr are applied by an operator (no attestation
+   machinery — out of scope).
+4. **Infrastructure is Consumed, Not Maintained.** No node/OS/bare-metal
+   lifecycle. The platform manages environments (accounts, VPCs, state
+   backends); consumers provide none.
+5. **One Consumer Surface.** A consumer writes a YAML contract and a
+   thin shell invocation. That is the entire surface.
+
+## Domain Boundaries
+
+- **In scope:** environment progression; cloud resource lifecycle;
+  contract resolution; Terraform adapter; module catalog (L1 primitives +
+  L2 patterns); local shell reproducibility; offline tests.
+- **Out of scope:** application business logic; IDE workflows; product
+  backlog; security scoring; policy enforcement; audit ledger;
+  confidence signals; identity/ABAC; HITL attestation; reusable CI
+  workflows; metrics/telemetry of the platform itself.
+- **Interface:** upstream systems integrate through the contract
+  boundary (`schemas/contract.schema.json`). The platform validates,
+  resolves, and reconciles the target state.
+
+## Scope: Nova Platform is Downstream of PDLC
+
+The Product Development Lifecycle (PDLC) — product backlog, code
+authorship, IDE workflows, application business logic — is **upstream**
+of Nova Platform. Nova Platform never reaches into the PDLC. Its domain
+is **infrastructure + delivery only**: environment progression, cloud
+resource lifecycle.
+
+Integration between the PDLC and Nova Platform is **only** through the
+validated contract boundary (`schemas/contract.schema.json`).
+
+## Decisions (locked in init)
+
+- **D-001:** Milestone type = `major` (first release, no prior tags).
+  The final phase of v1.0 ships `v1.0.0` and that IS the initial release.
+- **D-002:** Module count for v1.0 = all 13 L1 primitives + 2 L2 patterns
+  in one milestone (matches the reference v1.0 shape).
+- **D-003:** `config.git.branching_strategy` = `phase` (canonical
+  CIAgent branch hierarchy; fresh project).
+- **D-004:** `config.git.auto_commit` / `auto_push` = `true` / `true`.
+- **D-005:** `config.verification.test_first` = `false`.
+- **D-006:** Personas = lead-developer + data-engineer (terraform) +
+  backend-engineer (core python); frontend-engineer deactivated (no UI).
+- **D-007:** `config.policy` removed entirely (no policy engine).
+  `config.ideation.categories` reduced to quality/architecture/coverage/
+  improvement (security dropped).
+- **D-008:** `config.secrets.scopes` = forge/gitea/github/gitlab +
+  openai/anthropic/ollama_cloud (model backends). `NOVA_FORGE_TOKEN` is
+  the gitea scope var.
+- **D-009:** `config.ship.confirm_before_ship` = `true` (supervised
+  autonomy escalates on ship).
+- **D-010:** `config.telemetry.persist` = `true` (CIAgent telemetry !=
+  platform metrics; the metrics layer is dropped but CIAgent's own
+  run audit trail is preserved).
@@ -0,0 +1,200 @@
+# Nova Platform — Requirements (v1.0)
+
+> Inaugural milestone. Builds the simplified infrastructure-delivery
+> platform derived from the Nova reference (`acdl`). The security/policy
+> /identity/audit/CI-pipeline machinery of the reference is
+> intentionally out of scope (see `PROJECT.md` decisions D-007).
+
+## Decisions (locked in init CLARIFY, supervised autonomy)
+
+- **D-001:** Milestone type = `major` (first release, no prior tags).
+  The final phase of v1.0 ships tag `v1.0.0` — that IS the initial
+  release. No separate milestone minor tag (major milestone: the final
+  phase's patch line starts the new major).
+- **D-002:** v1.0 ships all 13 L1 primitives + 2 L2 patterns in one
+  milestone (matches reference v1.0 shape).
+- **D-003:** `config.git.branching_strategy` = `phase`.
+- **D-004:** `auto_commit` / `auto_push` = `true` / `true`.
+- **D-005:** `test_first` = `false`.
+- **D-006:** Personas = lead-developer + data-engineer + backend-engineer
+  (frontend-engineer deactivated, no UI).
+- **D-007:** `config.policy` removed; `ideation.categories` reduced
+  (security dropped).
+- **D-008:** `secrets.scopes` keeps forge + model-backend scopes.
+- **D-009:** `ship.confirm_before_ship` = `true` (supervised ship gate).
+- **D-010:** `telemetry.persist` = `true` (CIAgent audit trail only).
+
+## Category: Contract Surface (feat)
+
+- **REQ-01:** `schemas/contract.schema.json` (JSON Schema draft
+  2020-12) defines the contract envelope: `id` (string, required),
+  `name` (string, required), `environment` (string, required, one of
+  `dev|qa|prod|dr`), `infrastructure` (array, required, min 1 item) of
+  objects each with `module` (string), `version` (semver string), and
+  `inputs` (object). No `aws_*` or engine terms permitted in the
+  schema. Validated by `tests/test_contract_schema.py`.
+- **REQ-02:** `contracts/static-assets.yaml` and
+  `contracts/microservice.yaml` are sample consumer contracts that
+  validate against REQ-01. Each has per-environment variants
+  (`*.dev.yml`, `*.qa.yml`, `*.prod.yml`, `*.dr.yml`).
+
+## Category: Resolution (feat)
+
+- **REQ-03:** `core/contract_resolver.py` exposes
+  `resolve(contract: dict, registry: dict) -> dict` that takes a
+  validated contract and the module registry and returns a Stack
+  instance conforming to `schemas/stack.schema.json`. Pure function:
+  no I/O, no engine terms. Raises `ModuleNotFoundError` on unknown
+  module, `VersionNotFoundError` on unknown version.
+- **REQ-04:** `schemas/stack.schema.json` defines the Stack shape:
+  `contract_id`, `contract_name`, `environment`, and `resources`
+  (array of `{module, version, inputs}` — NO `source` field; the
+  adapter loads `registry.json` to resolve `module` → `terraform_dir`
+  per C-1 grill fix). The stack is engine-agnostic: no `source`, no
+  Terraform paths, no `aws_*` terms (engine terms appear only in the
+  adapter + modules/terraform/, NOT in the contract or stack).
+- **REQ-05:** `core/environment_check.py` exposes
+  `check(env_name: str, environments_dir: Path) -> dict` that loads
+  `core/environments/<env_name>.json` and returns the environment
+  record (account, region, state_backend). Raises
+  `EnvironmentNotFoundError` on missing env.
+- **REQ-06:** `core/environments/dev.json` is the sample dev
+  environment (offline-friendly: uses local emulators where possible,
+  AWS where required).
+
+## Category: Engine Adapter (feat)
+
+- **REQ-07:** `adapters/terraform/adapter.py` exposes
+  `adapt(stack: dict, repo_root: Path) -> str` that takes a Stack and
+  the repo root Path, loads `modules/registry.json` internally to map
+  `module` → `terraform_dir`, and emits Terraform HCL: a
+  `module "x" { source = ...; <inputs> }` block per resource. Stateless
+  assembler — no `terraform` invocation, no state files, no plan files.
+  The ONLY place `aws_*` / Terraform terms appear in code (per C-1
+  grill fix — the adapter loads the registry inside the engine
+  boundary, not the resolver).
+- **REQ-08:** `adapters/terraform/__init__.py` re-exports `adapt`.
+  The adapter is behind no protocol (single engine; the reference's
+  `PolicyEngine` pattern is out of scope).
+- **REQ-09:** `tests/test_engine_boundary.py` asserts that no file
+  outside `adapters/terraform/` contains the strings `aws_`, `module "`,
+  `terraform`, `provider "`, or `resource "`. Engine agnosticism is
+  verified by grep, not by convention.
+
+## Category: Module Catalog (feat)
+
+- **REQ-10:** `modules/registry.json` indexes every module + version
+  with `{interface, terraform_dir, published_at, deprecated, kind}`.
+  Matches the reference's registry shape exactly.
+- **REQ-11:** Each L1 primitive has `modules/l1/<name>/interface.json`
+  (inputs/outputs, no engine terms) and
+  `modules/l1/<name>/terraform/main.tf`. Primitives (13): s3, vpc,
+  ecs-cluster, ecs-service, iam-role, alb, ecr, cloudfront, waf, rds,
+  kms-key, dynamodb, uptime.
+- **REQ-12:** Each L2 pattern has `modules/l2/<name>/interface.json`
+  and `modules/l2/<name>/terraform/main.tf` that composes L1
+  primitives via `module` blocks. Patterns (2): microservice,
+  static-assets.
+- **REQ-13:** `modules/README.md` documents the L1/L2 distinction,
+  the registry format, and how to add a module. Matches the
+  reference's `modules/README.md` shape (minus the security/attestation
+  sections).
+
+## Category: Terraform Bootstrap + Platform (feat)
+
+- **REQ-14:** `terraform/bootstrap/create_state_backend.py` creates
+  the S3 + DynamoDB state backend (idempotent). Mirrors the reference's
+  bootstrap script shape.
+- **REQ-15:** `terraform/bootstrap/create_iam_user.py` creates the
+  runner IAM user + policy (idempotent). Prints the initial key.
+- **REQ-16:** `terraform/ci-vpc/main.tf` defines the shared platform
+  VPC used by all stacks.
+- **REQ-17:** `terraform/platform/main.tf` defines platform-level
+  resources (state bucket references, runner role).
+- **REQ-18:** `terraform/microservice/main.tf` is a sample consumer-
+  facing Terraform root that the microservice L2 pattern deploys into.
+- **REQ-19:** `terraform/onboarding/main.tf` defines the onboarding
+  stack (creates a consumer's IAM role scoped to their repo tags).
+  Simplified from the reference (no OIDC — static key alternative
+  only, documented in README).
+
+## Category: Local Shell Reproducibility (feat)
+
+- **REQ-20:** `scripts/run_platform.sh` orchestrates the full
+  pipeline: contract → resolver → adapter → security (skipped —
+  no policy layer) → plan → apply. Flags: `--check-only` (offline,
+  contract → resolver → adapter → structure validation, exits 0 on
+  success), `--plan-only` (no apply), `--quiet` (suppress streaming),
+  `--help`. Default mode (no flag) applies. Streams output by default.
+- **REQ-21:** `scripts/run_ci.sh` mirrors a CI pipeline locally:
+  lint (py_compile) → test (pytest) → check-only
+  (`run_platform.sh --check-only`). Three stages in sequence.
+  `--quiet` suppresses banners.
+- **REQ-22:** `scripts/rotate_spike_key.sh` rotates the runner key
+  into `.env.secrets` (gitignored, chmod 600). Mirrors the reference.
+
+## Category: Offline Test Suite (feat)
+
+- **REQ-23:** `tests/test_contract_resolver.py` — unit tests for
+  `resolve()` covering happy path, unknown module, unknown version,
+  empty infrastructure array.
+- **REQ-24:** `tests/test_environment_check.py` — unit tests for
+  `check()` covering existing env, missing env, malformed env file.
+- **REQ-25:** `tests/test_terraform_adapter.py` — unit tests for
+  `adapt()` covering single-resource stack, multi-resource stack,
+  input passthrough, HCL syntax validity.
+- **REQ-26:** `tests/test_engine_boundary.py` — grep-based test for
+  REQ-09 (no engine terms outside `adapters/terraform/`).
+- **REQ-27:** `tests/test_contract_schema.py` — validates sample
+  contracts against `schemas/contract.schema.json` using `jsonschema`.
+- **REQ-28:** `tests/test_stack_schema.py` — validates resolved stacks
+  against `schemas/stack.schema.json`.
+- **REQ-29:** `tests/test_run_platform_check_only.py` — invokes
+  `scripts/run_platform.sh --check-only` and asserts exit 0 + the
+  "PLATFORM CHECK OK" banner. Offline (uses local emulators / moto).
+- **REQ-30:** `tests/test_run_ci.sh` — invokes `scripts/run_ci.sh`
+  and asserts exit 0 + the "CI PIPELINE OK" banner.
+- **REQ-31:** `requirements-test.txt` pins `pytest`, `moto`, `jsonschema`,
+  `boto3`, `pyyaml`. `pyproject.toml` configures pytest + py_compile.
+
+## Category: Documentation (feat)
+
+- **REQ-32:** `README.md` covers: what the platform is, how to run
+  offline (`run_platform.sh --check-only`), how to run the test suite,
+  how to run against live AWS, repository layout table, credentials
+  (static key alternative only — no OIDC), consumer guide pointer.
+- **REQ-33:** `docs/architecture.md` is the source of truth for how
+  the platform works (mirrors `.ciagent/ARCHITECTURE.md`).
+- **REQ-34:** `docs/modules/` documents each L1 primitive + L2 pattern
+  (one .md per module, same shape as the reference).
+- **REQ-35:** `docs/contracts/` documents the contract schema + sample
+  contracts.
+- **REQ-36:** `docs/environments/` documents the environment model +
+  the sample dev environment.
+- **REQ-37:** `docs/consumer-guide.md` is the step-by-step guide for
+  a consumer to write a contract and deploy (infra-only — no security
+  sections).
+- **REQ-38:** `.gitignore` seeds `.env`, `.env.secrets`, `.env.*`,
+  terraform state, credentials, `__pycache__/`, `.ciagent/logs/`.
+
+## Out of scope (locked — do NOT implement in v1.0)
+
+- Security/policy: kyverno-json, Wiz, Checkov custom rules,
+  `PolicyEngine`, `PolicyCheckResult` gating, `core/policy_engine.py`.
+- Confidence + evidence: `core/confidence_signal.py`,
+  `core/outbox_writer.py`, audit ledger, attestation matrix.
+- Identity/ABAC: Nova-idp, PAT lifecycle, `core/abac_evaluator.py`,
+  `core/auth_store.py`, `core/jws_attestation.py`, `core/kms_signing.py`,
+  `core/pat_lifecycle.py`, `core/separation_of_duties.py`,
+  `core/hitl_gates.py`, `core/attestation_matrix.py`,
+  `core/submission_readiness.py`.
+- CI/CD pipeline: `.github/workflows/ci.yml`,
+  `.github/workflows/deploy.yml`, `pipelines/`,
+  `schemas/pipeline.schema.json`, `schemas/deploy-pipeline.schema.json`.
+- Metrics/telemetry: `metrics/`, `core/metrics/`,
+  `core/regression_verify*.py`.
+- Leadership decks, PPTX, marp slides.
+- Decommission alias, env_transition, mode_resolver, onboarding flow
+  beyond bootstrap.
+- Multi-project mode, consumer subprojects.
+- OIDC federation (plain static AWS key for dev only).
@@ -0,0 +1,331 @@
+# RESEARCH — Nova Platform v1.0
+
+> Phase 0 RESEARCH artifact. Derived from structural analysis of the Nova
+> reference at `/home/opencode/acdl/`. Each section documents the
+> reference's exact shape so execution phases can mirror it, then notes
+> the nova-platform adaptation referencing the locked decisions
+> (D-001..D-035 in `.ciagent/CLARIFY.md` + `.ciagent/PROJECT.md`).
+>
+> **Scope rule:** security/audit/identity/CI-workflow machinery is OUT OF
+> SCOPE. Files related to those subsystems were NOT read. This document
+> covers only the in-scope infrastructure-delivery core.
+
+---
+
+## 1. `schemas/contract.schema.json` — contract envelope
+
+### Reference shape
+- JSON Schema draft 2020-12. `$id: https://nova.cloudinit.dev/schemas/contract.schema.json`. Title `Nova Consumer Contract`.
+- Top-level `type: object`, `required: ["id", "name", "environment", "infrastructure"]`, `additionalProperties: false`.
+- `id`: `type: string`, `pattern: ^[a-z][a-z0-9-]{2,5}$` (3-6 char operational acronym).
+- `name`: `type: string`, `minLength: 3` (human-readable).
+- `environment`: `type: string`, `enum: [dev, qa, prod, dr]`.
+- `infrastructure`: **OBJECT** (map), `minProperties: 1`, `additionalProperties: false`. `patternProperties` keyed by `^[a-z][a-z0-9-]*$` (module name). Each entry is an object `required: ["inputs"]` with `version` (optional, semver `^\d+\.\d+\.\d+$`) and `inputs` (object, `additionalProperties` allowing string/number/boolean/object/array), `additionalProperties: false` on the entry.
+- The contract is the ONLY consumer surface. Engine-agnostic: no `aws_*` terms in the schema keywords.
+
+### Nova-platform adaptation (REQ-01 + D-015)
+- Same draft 2020-12, same `$id` host, same title pattern.
+- Same `id` pattern, same `name` minLength, same `environment` enum.
+- **KEY DEVIATION:** `infrastructure` is an **ARRAY** (per REQ-01 + D-015), not the reference's object map. `type: array`, `minItems: 1`. Each item is an object `required: ["module", "inputs"]` (NOT keyed by module name — the module name is a field). Fields per item: `module` (string, required), `version` (string, optional, semver pattern — defaults to latest non-deprecated per D-015), `inputs` (object, required, `additionalProperties: false` allowing primitives/objects/arrays).
+- No `aws_*` or engine terms in the schema. Validated by `tests/test_contract_schema.py` (REQ-27).
+
+---
+
+## 2. `schemas/stack.schema.json` — resolved stack shape
+
+### Reference shape
+- Draft 2020-12. Title `Nova Target Stack`. `required: ["version", "stack", "resources"]`.
+- `version`: semver string. `stack`: object `required: ["name", "kind", "depth"]`.
+- `resources`: array of `$defs/resource` — each `required: ["id", "type", "module", "inputs"]`. `id` pattern `^[a-z][a-z0-9-]*$`. `type` is stack-typed (`aws:s3:bucket`, NOT `aws_s3_bucket`). `module` is `name@semver`. Optional `parent`, `outputs`, `nfrs`.
+- Optional `relationships` array. Schema body is engine-agnostic.
+
+### Nova-platform adaptation (REQ-04 + D-012)
+- **FLAT shape** per D-012. `required: ["contract_id", "contract_name", "environment", "resources"]`.
+- `contract_id`, `contract_name` (strings), `environment` (string enum).
+- `resources`: array of `{module, version, source, inputs}` where `source` is a Terraform module path (engine terms appear HERE only — the stack is the resolved form passed to the adapter, NOT the contract).
+- NO `stack` wrapper, NO `relationships`, NO `nfrs`, NO `data_sources`, NO `outputs` map. L2 is opaque per D-012.
+
+---
+
+## 3. `schemas/environment.schema.json` — environment record
+
+### Reference shape
+- Draft 2020-12. `required: ["name", "account_id", "region", "state_backend", "network", "runner_role_arn", "autonomy", "confidence_threshold"]`.
+- `account_id`: 12-digit pattern (placeholder `000000000000` allowed). `state_backend`: `{bucket, lock_table}`. `network`: `{vpc_cidr, azs}`. `runner_role_arn`, `autonomy` enum, `confidence_threshold` 0-1.
+- `additionalProperties: false` on top level.
+
+### Nova-platform adaptation (D-017 + D-018)
+- **KEEP** the schema (D-017) but **simplify** the required field set per D-018.
+- `required: ["name", "account_id", "region", "state_backend", "network"]`.
+- **DROP** `runner_role_arn` (ABAC OOS), `autonomy` (HITL OOS), `confidence_threshold` (OOS).
+- Keep `description` optional, `account_id` 12-digit pattern + placeholder warning, `region`, `state_backend {bucket, lock_table}`, `network {vpc_cidr, azs}`. `additionalProperties: false`.
+
+---
+
+## 4. `core/contract_resolver.py` — resolve() function
+
+### Reference shape
+- `resolve(contract_path, repo_root=None, environment_override=None) -> dict`. Takes a **file path** to contract YAML. Loads YAML, loads env via `environment_check.load()`, builds interpolation context `{"env": env, "contract": contract}`. Expands `${env.*}` / `${contract.*}` AFTER schema validation, BEFORE IR resolution.
+- `_TOKEN_RE = re.compile(r"\$\{([a-zA-Z_][a-zA-Z0-9_.]*)\}")`. `_lookup_dotted(context, dotted)`. `_expand_vars(value, context)` recurses; unknown token raises `ValueError`.
+- `_latest_version(registry, module_name)`. `_resolve_l1(...)` builds resource from interface.json. `_resolve_l2(...)` loads composition.json, expands children/wires/data_sources.
+- Exceptions: generic `ValueError` strings (no custom classes). CLI delegates to `contract_resolver_cli.main`.
+
+### Nova-platform adaptation (REQ-03 + D-011 + D-016)
+- **Signature per D-011:** `resolve(contract: dict, registry: dict, modules_dir: Path) -> dict`. Takes a **validated contract dict** (not a path), a **registry dict**, and a **modules_dir Path**. "Pure" = no network/side-effects; local file reads for module metadata ARE permitted.
+- **Interpolation KEPT** (D-016): `_TOKEN_RE`, `_lookup_dotted`, `_expand_vars` preserved verbatim (engine-agnostic). Unknown token raises `ValueError`.
+- **Named exceptions per REQ-03:** `ModuleNotFoundError` (unknown module), `VersionNotFoundError` (unknown version) — REPLACE the reference's generic `ValueError` strings.
+- **L2 = opaque per D-012:** NO `_resolve_l2` composition expansion. L2 is a single stack resource `{module, version, source, inputs}`. NO children/wires/data_sources.
+- **NO policy evaluation, NO CLI module.** Run as script. Returns the flat stack dict per REQ-04.
+
+---
+
+## 5. `core/environment_check.py` — check()/load()
+
+### Reference shape
+- `load(env_name, root=None) -> dict` — raises `FileNotFoundError`. `check(contract_path, env_name, root) -> (ok, message)` tuple. `_onboarding_message(env_name)` friendly prompt. `main(argv)` CLI.
+
+### Nova-platform adaptation (REQ-05 + D-019)
+- **Signature per D-019:** `check(env_name: str, environments_dir: Path) -> dict`. Returns the **env dict** directly. Raises `EnvironmentNotFoundError` on missing env.
+- **DROP** `_onboarding_message`, `contract_path` param, `main()` CLI. `load()` folded into `check()` or kept as internal helper.
+
+---
+
+## 6. `adapters/terraform/` — the Terraform adapter
+
+### Reference shape
+- `adapters/terraform/adapter.py` + `policy/` (OOS). **NO `__init__.py`**.
+- `adapt(stack_instance, out_dir)` — emits THREE files: `main.tf` (module blocks + data blocks + root outputs), `terraform.tf` (required_version + required_providers + s3 backend env-scoped key), `providers.tf` (`provider "aws"`).
+- `_tf_value`, `_ref_expr`, `_module_name`, `_emit_module_block`, `_emit_root_output`. Multi-resource L1 dedup (`_child_id`).
+- Statelessness guards: no TYPE_MAP/INPUT_MAP/OUTPUT_MAP, < 250 lines.
+
+### Nova-platform adaptation (REQ-07 + REQ-08 + D-013)
+- **File layout:** `adapters/terraform/adapter.py` + `adapters/terraform/__init__.py` (re-exports `adapt`). **NO `policy/`**.
+- **Signature per REQ-07:** `adapt(stack: dict, modules_dir: Path) -> str`. Returns HCL string (caller writes main.tf). Stateless assembler — no terraform invocation, no state, no plan.
+- Emits `module "x" { source = ...; <inputs> }` per resource. L2 `source` = `modules/l2/<name>/terraform` (D-013). `ref:` translation + multi-resource dedup SIMPLIFIED (L2 opaque, flat stack has no refs).
+- `region` skip + provider-level region pattern preserved. terraform.tf + providers.tf emitted by small helper or `run_platform.sh`.
+- **Engine boundary:** ONLY place `aws_*` / `terraform` / `module "` / `provider "` / `resource "` appear (REQ-09).
+
+---
+
+## 7. `modules/registry.json` — module index
+
+### Reference shape
+- Top-level object keyed by module name → version string → entry. L1: `{interface, terraform_dir, published_at, deprecated, kind:"l1"}`. L2: `{interface, published_at, deprecated, kind:"l2"}` — **NO `terraform_dir`**.
+- 13 L1 + 2 L2 = 15 entries.
+
+### Nova-platform adaptation (REQ-10 + D-013)
+- **Matches reference shape exactly** per REQ-10.
+- **DEVIATION per D-013:** L2 entries DO include `terraform_dir: "modules/l2/<name>/terraform"` (required by flat stack's `source` field).
+- L2 `interface` points at `modules/l2/<name>/interface.json` (NOT `composition.json`). Same 15 entries, same names.
+
+---
+
+## 8. `modules/l1/s3/` — representative L1 primitive
+
+### Reference shape
+- `interface.json`: `{name, version, kind:"l1", type, description, inputs, outputs, nfrs, resources?, intra_refs?}`. `type` stack-typed (`aws:s3:bucket`). `inputs`/`outputs` keyed by name → `{type, description, required?, default?}`.
+- `terraform/`: `main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`, `locals.tf`. `count = var.enabled ? 1 : 0`. `required_version = ">= 1.9, < 1.10"`. `aws = { source = "hashicorp/aws"; version = "~> 5.0" }`.
+- `README.md` (follows README-TEMPLATE.md), `instance.json`, `examples/`.
+
+### Nova-platform adaptation (REQ-11 + D-014)
+- `interface.json` per D-014: KEEP `name, version, kind, type, description, inputs, outputs, resources` (multi-resource array for vpc/ecs-service/alb). **DROP `nfrs`** (confidence signal OOS) and **DROP `intra_refs`** (wire engine eliminated by D-012).
+- `terraform/` shape preserved (5 files, same HCL conventions). All 13 L1 primitives authored.
+- Per D-035: L1 `s3` stays reference interface (`bucket_name`/`region`/`kms_key_arn`/`enabled`) — does NOT gain `index_document`.
+
+---
+
+## 9. `modules/l2/microservice/` — L2 pattern
+
+### Reference shape
+- `composition.json`: `{name, version, kind:"l2", depth, children[], data_sources[], wires[], outputs[]}`. ~24 wires. **NO `terraform/` directory** (resolver expands; adapter emits per-L1 blocks).
+
+### Nova-platform adaptation (REQ-12 + D-012 + D-013)
+- **`interface.json` replaces `composition.json`** per D-013. Content: `{name, version, kind:"l2", description, inputs, outputs}` — L2-level only, NO children/wires.
+- **`terraform/main.tf` ADDED** per D-012: composes L1 internally via `module` blocks. Resolver treats L2 as single resource; adapter emits one `module "microservice" { source = "modules/l2/microservice/terraform" }` block. L2's `main.tf` instantiates `module "cluster" { source = "../../l1/ecs-cluster/terraform" }` etc.
+- 2 L2 patterns: microservice (vpc + ecs-cluster + ecs-service + iam-role + ecr + alb), static-assets (s3 + cloudfront + kms-key).
+
+---
+
+## 10. `scripts/run_platform.sh` — platform pipeline orchestrator
+
+### Reference shape
+- `set -euo pipefail`. Flag parsing: `--check-only`, `--plan-only`, `--apply`, `--destroy`, `--quiet`, `--deploy-uptime`, `--decommission`, `--local`, `--environment`, `--help`.
+- Stages: env check → validate contract → resolve → adapter → [check-only: validate output → exit 0] → load AWS creds (NOVA_AWS_* → AWS_*) → terraform init/validate/plan → [plan-only: exit 0] → apply → E2E OK.
+- Banners: `=== PLATFORM CHECK OK ===`, `=== PLATFORM PLAN OK ===`, `=== PLATFORM APPLY OK ===`, `=== PLATFORM E2E OK ===`.
+
+### Nova-platform adaptation (REQ-20 + D-020 + D-031 + D-032)
+- **Flags per D-031:** ONLY `--check-only`, `--plan-only`, `--quiet`, `--help` (+`-h`). Default = apply. DROP all others.
+- **Stages per D-020:** check-only (offline): env_check → validate → resolve → adapter → validate output → `=== PLATFORM CHECK OK ===`. plan-only: + creds → init/validate/plan → `=== PLATFORM PLAN OK ===`. default: + apply → `=== PLATFORM APPLY OK ===`.
+- **AWS creds per D-032:** `NOVA_AWS_*` prefix → `AWS_*` copy, then unset `NOVA_AWS_*`.
+- DROP: env_transition, Checkov, kyverno-json, confidence, HITL, outbox, output publisher, uptime, decommission, local emulators.
+
+---
+
+## 11. `scripts/run_ci.sh` — local CI pipeline mirror
+
+### Reference shape
+- 3 stages: lint (py_compile, hardcoded file list) → test (pytest) → check-only. `=== CI PIPELINE OK ===`.
+
+### Nova-platform adaptation (REQ-21 + D-021)
+- Same 3-stage flow. **Stage 1 per D-021:** glob `python3 -m py_compile $(find core/ adapters/ scripts/ -name '*.py')` (no hardcoded list — no OOS Python files exist).
+- Banners preserved. `--quiet` suppresses banners.
+
+---
+
+## 12. `terraform/bootstrap/` — state backend + IAM user scripts
+
+### Reference shape
+- `create_state_backend.py`: S3 `nova-tfstate-<account>-us-east-1` + DynamoDB `nova-outbox`. Idempotent. `NOVA_BOOTSTRAP_AWS_*` (fallback `NOVA_AWS_*`).
+- `create_iam_user.py`: IAM user `nova-spike-runner` + inline policy + key. Prints `NOVA_AWS_*`.
+- `spike_runner_policy.json`: hardcoded account `581513795199`.
+
+### Nova-platform adaptation (REQ-14 + REQ-15 + D-022 + D-026)
+- `create_state_backend.py` per D-022: S3 `nova-tfstate-<account>-<region>` + **DynamoDB `nova-tfstate-locks`** (NOT `nova-outbox`). Idempotent.
+- `create_iam_user.py` per D-026: user `nova-spike-runner` + policy + key. Account ID **parameterized** (NOT hardcoded).
+- `spike_runner_policy.json`: account parameterized. Grants S3/DynamoDB lock/ECS/ECR/ELB/IAM/EC2/CloudFront/WAF/KMS. **DROP** Lambda, Secrets, SNS, CostExplorer, OIDC.
+
+---
+
+## 13. `terraform/platform/main.tf` — platform infrastructure
+
+### Reference shape
+- 367 lines: KMS, DynamoDB contracts, Secrets, Lambda, SNS, **shared VPC**, outputs `vpc_id`/`subnet_ids`/`ecs_security_group_id`.
+
+### Nova-platform adaptation (REQ-17 + D-023)
+- **ONLY shared platform VPC** per D-023: `aws_vpc.nova_shared`, `aws_subnet.nova_shared` (count=2), IGW, route table, ECS SG. Outputs `vpc_id`, `subnet_ids`, `ecs_security_group_id`.
+- **DROP** Lambda, DynamoDB, KMS, Secrets, SNS, consumer_invoke_policy — ALL OOS.
+
+---
+
+## 14. `terraform/ci-vpc/main.tf` — short-lived test VPC
+
+### Reference shape
+- Short-lived VPC for module lifecycle testing. VPC + 2 subnets + IGW + route table + ECS SG + ECS cluster. Outputs `vpc_id`/`subnet_ids`/`ecs_security_group_id`/`cluster_arn`. State key `spike/ci-vpc/terraform.tfstate`.
+
+### Nova-platform adaptation (REQ-16 + D-024)
+- **Preserved** per D-024. Short-lived test VPC. Shared platform VPC lives in `terraform/platform/main.tf`. Same shape.
+
+---
+
+## 15. `terraform/onboarding/main.tf` — consumer onboarding stack
+
+### Reference shape
+- IAM role `nova-<consumer_repo>-deploy` with **OIDC** trust. Inline policy `lambda:InvokeFunctionUrl` (ABAC). Outputs `consumer_deploy_role_arn`/`consumer_deploy_role_name`.
+
+### Nova-platform adaptation (REQ-19 + D-025)
+- **IAM ROLE (not user)** per D-025 (human override). Trust policy allows **platform's runner user** to assume it (**cross-account assume role**, `sts:AssumeRole`). **NO OIDC**.
+- `consumer_repo`/`owner_id` vars for tagging. Inline policy: Terraform-deployable permissions scoped via tags. **DROP** `lambda:InvokeFunctionUrl`.
+- Outputs `consumer_deploy_role_arn`/`consumer_deploy_role_name`. README documents dev-only static-key.
+
+---
+
+## 16. `terraform/microservice/main.tf` — sample consumer Terraform root
+
+### Reference shape
+- 147 lines. Hand-authored root: VPC, subnets, ECS cluster, ECR, IAM role, ALB, listener, task def, ECS service. Companion `terraform.tf` + `providers.tf`.
+
+### Nova-platform adaptation (REQ-18)
+- Preserved as sample consumer-facing root. **Simplified** to opaque L2 model (D-012): L2's own `modules/l2/microservice/terraform/main.tf` composes L1 via `module` blocks. `terraform/microservice/main.tf` instantiates the L2 module + wires to platform VPC via `data.terraform_remote_state`.
+- State key `spike/microservice/<env>/terraform.tfstate` (env-scoped).
+
+---
+
+## 17. `tests/` — test file naming + structure
+
+### Reference shape
+- `conftest.py`: `ROOT` + `sys.path.insert`. Fixtures: `repo_root`, `stack_instance`, `stack_schema`, `registry`, `policy_check_result_schema`.
+- `test_contract_resolver.py`, `test_environment_check.py`, `test_adapter.py` (classes for instance, registry, module assembly, ref expr, tf value, statelessness, valid terraform, dedup).
+
+### Nova-platform adaptation (REQ-23..REQ-30)
+- `conftest.py`: `repo_root`, `stack_schema`, `registry`. **DROP** `stack_instance` + `policy_check_result_schema`.
+- `test_contract_resolver.py` (REQ-23): `resolve(contract, registry, modules_dir)` — happy path, `ModuleNotFoundError`, `VersionNotFoundError`, empty infrastructure.
+- `test_environment_check.py` (REQ-24): `check(env_name, environments_dir)` — existing env, `EnvironmentNotFoundError`, malformed.
+- `test_terraform_adapter.py` (REQ-25): `adapt(stack, modules_dir)` — single/multi resource, input passthrough, HCL validity.
+- `test_engine_boundary.py` (REQ-26 + D-034): grep `.py` files only (core/schemas/contracts/tests/scripts/root), exclude `adapters/terraform/`/modules/.tf/.md/.json.
+- `test_contract_schema.py` (REQ-27), `test_stack_schema.py` (REQ-28), `test_run_platform_check_only.py` (REQ-29), `test_run_ci.sh` (REQ-30).
+
+---
+
+## 18. `pyproject.toml` — pytest config + project metadata
+
+### Reference shape
+- `[project] name = "nova"`, `[project.scripts] nova = "nova.cli:main"`. test deps include pytest-cov, pytest-json-report, hypothesis. `addopts` writes to `metrics/`.
+
+### Nova-platform adaptation (REQ-31 + D-027)
+- **No CLI package** per D-027. `[project] name = "nova-platform"`. **NO `[project.scripts]`**. NO `nova/` dir.
+- test deps: `pytest>=8.0, moto[dynamodb]>=5.0, jsonschema>=4.20, pyyaml>=6.0, boto3>=1.34`. **DROP** pytest-cov, pytest-json-report, hypothesis.
+- `addopts = "-v --tb=short"` (no metrics/). `markers = [offline, slow]`. `[tool.setuptools.packages.find]` includes `core, core.*, adapters.*` (NO `nova`).
+
+---
+
+## 19. `requirements-test.txt`
+
+```
+pytest>=8.0
+moto[dynamodb]>=5.0
+jsonschema>=4.20
+pyyaml>=6.0
+boto3>=1.34
+```
+
+(DROP `pytest-cov` — no coverage reporting.)
+
+---
+
+## 20. `.gitignore`
+
+Already seeded in nova-platform (matches reference minus OOS metrics lines). Contains `__pycache__/`, `.env*`, terraform state, credentials, `.ciagent/logs/`, `nova_platform.egg-info/`.
+
+---
+
+## 21. `modules/README.md` + `modules/README-TEMPLATE.md`
+
+### Reference shape
+- `README.md` (63 lines): Primitives vs Modules, tables, registry, template link. `README-TEMPLATE.md` (62 lines): Overview/Resources/Inputs/Outputs/NFRs/Usage/Compliance/Versioning. `STANDARDS.md` (673 lines — security/compliance).
+
+### Nova-platform adaptation (REQ-13 + D-029)
+- `modules/README.md`: L1/L2 distinction, registry format, how to add a module. **Trimmed of security/attestation**. 13-row primitives table, 2-row modules table.
+- `modules/README-TEMPLATE.md`: KEEP. Sections: Overview/Resources/Inputs/Outputs/Usage/Versioning. **DROP NFRs + Compliance** sections.
+- **DROP `modules/STANDARDS.md`** per D-029.
+
+---
+
+## 22. `docs/` — documentation shapes
+
+### Reference shape
+- `docs/modules/index.md` (catalog → links to `modules/*/README.md`). `docs/contracts/index.md` (fields table, samples). `docs/environments/index.md` (env model, autonomy table). `docs/consumer-guide.md` (513 lines, 9 steps). `docs/architecture.md` (241 lines, 4 layers + cross-cutting).
+
+### Nova-platform adaptation (REQ-32..REQ-37)
+- `docs/modules/index.md` (REQ-34 + D-028): catalog table linking to `modules/*/README.md` (per-module docs live in `modules/`, not `docs/modules/`).
+- `docs/contracts/index.md` (REQ-35): array-based `infrastructure` schema + samples + per-env variants (D-033).
+- `docs/environments/index.md` (REQ-36): env model (account/network/state backend — NO IAM role/ABAC). Autonomy table simplified (dev autonomous; qa/prod/dr manual operator — NO HITL gates).
+- `docs/consumer-guide.md` (REQ-37): infra-only. Steps: create repo, write contract, run check-only, run against AWS. Keep interpolation table. DROP OIDC/reusable-workflow/decommission/compliance.
+- `docs/architecture.md` (REQ-33): mirrors `.ciagent/ARCHITECTURE.md`. Four layers + engine boundary + OOS list + module catalog. NO cross-cutting concerns sections.
+
+---
+
+## Cross-cutting observations
+
+### Engine-agnostic invariant
+`schemas/contract.schema.json` + `schemas/stack.schema.json` + `core/contract_resolver.py` + `core/environment_check.py` contain NO `aws_*` / Terraform terms. ONLY `adapters/terraform/` is engine-specific. Verified by `tests/test_engine_boundary.py` (D-034 — grep `.py` only).
+
+### Structural conventions preserved without deviation
+- Directory names: `schemas/`, `core/` (+ `core/environments/`), `adapters/terraform/`, `modules/` (`l1/`, `l2/`, `registry.json`), `contracts/`, `scripts/`, `terraform/` (`bootstrap/`, `ci-vpc/`, `microservice/`, `onboarding/`, `platform/`), `tests/`, `docs/`.
+- File roles: `interface.json`, `terraform/main.tf` (+ variables/outputs/versions/locals), `registry.json` entry shape, schemas, shell scripts, bootstrap scripts.
+- Module interface shape: `{name, version, kind, type, description, inputs, outputs}` + `resources[]` for multi-resource L1s. Stack-typed `type` (`aws:s3:bucket`).
+- Registry entry shape: `{interface, terraform_dir, published_at, deprecated, kind}`.
+- Banner strings: `=== PLATFORM CHECK OK ===`, `=== PLATFORM PLAN OK ===`, `=== PLATFORM APPLY OK ===`, `=== CI PIPELINE OK ===`.
+- State key convention: `spike/<stack_name>/<environment>/terraform.tfstate` (env-scoped).
+- Tag convention: `nova:owner`, `nova:contract`, `nova:environment`, `nova:cost-center`.
+
+### Key deviations (locked in CLARIFY.md)
+- **D-012:** L2 is opaque (single stack resource, no children/wires expansion). Flat stack.
+- **D-013:** L2 uses `interface.json` (not `composition.json`) + `terraform_dir` in registry.
+- **D-015:** `infrastructure` is an ARRAY (not object map); `version` optional.
+- **D-017/D-018:** environment schema simplified (drops runner_role_arn/autonomy/confidence_threshold).
+- **D-019:** `check()` returns dict, raises `EnvironmentNotFoundError` (not tuple).
+- **D-022:** lock table `nova-tfstate-locks` (not `nova-outbox`).
+- **D-023:** `terraform/platform/main.tf` = ONLY shared VPC.
+- **D-025:** onboarding = IAM role cross-account assume (not OIDC, not user).
+- **D-027:** no CLI package (scripts only).
+- **D-029:** drop `STANDARDS.md`.
@@ -0,0 +1,77 @@
+# Nova Platform — Roadmap
+
+> Skeleton. The roadmapper refines phase detail during `/ci-run` phase 0.
+> Init establishes the milestone + phase count estimate.
+
+## Milestone v1.0 — Nova Platform Inaugural
+
+> **Type:** major (first release, no prior tags per D-001). The final
+> phase's tag IS the initial release (`v1.0.0`). Tags run on the v0.x
+> patch line — but since there is no prior minor, the first milestone's
+> phase 0 ships `v0.1.0`, execution phases ship `v0.1.1`..`v0.1.N`, and
+> the final phase ships `v1.0.0` (major bump).
+>
+> **Branch:** `milestone/v1.0-nova-platform` (already created in init).
+> **Phase 0:** `phase/00-pre-execution` (current).
+
+### Phase 0 — Pre-Execution (current)
+
+SPECIFY → CLARIFY → RESEARCH → PLAN → GRILL → MVP/UX CHECK → SHIP.
+
+Produces all `.ciagent/` markdown (PROJECT.md, ARCHITECTURE.md,
+ROADMAP.md, REQUIREMENTS.md, PERSONAS.md, PLAN.md, GRILL.md), research
+files, and the task-level plan. Ships as `v0.1.0`.
+
+### Phase 1 — Contract Surface + Schemas + Resolver
+
+Implements REQ-01..06 + REQ-23..28 (contract schema, stack schema,
+resolver, environment check, their tests). First vertical slice: a
+contract can be validated, resolved to a stack, and the stack validated
+— offline, no apply. Ships as `v0.1.1`.
+
+### Phase 2 — Terraform Adapter + Engine Boundary
+
+Implements REQ-07..09 + REQ-25..26 (adapter, engine-boundary test).
+Second slice: a stack can be compiled to Terraform HCL — offline, no
+apply. Ships as `v0.1.2`.
+
+### Phase 3 — L1 Primitives + Registry
+
+Implements REQ-10..11 (registry + all 13 L1 primitives). Third slice:
+the module catalog exists; the adapter can emit real module blocks.
+Ships as `v0.1.3`.
+
+### Phase 4 — L2 Patterns + Terraform Bootstrap + Platform
+
+Implements REQ-12 + REQ-14..19 (L2 patterns, bootstrap scripts,
+platform/microservice/onboarding Terraform). Fourth slice: the
+reference deployable patterns exist; AWS bootstrap is scripted. Ships
+as `v0.1.4`.
+
+### Phase 5 — Shell Reproducibility + Test Suite + Docs
+
+Implements REQ-20..22 + REQ-29..31 + REQ-32..38 (run_platform.sh,
+run_ci.sh, rotate_spike_key.sh, full test suite, README, docs/).
+Fifth slice: the platform is fully reproducible from the shell and
+documented. Ships as `v0.1.5`.
+
+### Phase 6 — Final Review + Ship (milestone release)
+
+REVIEW + AUDIT + milestone SHIP. Merges `phase/06` →
+`milestone/v1.0-nova-platform` → `main`. Tags `v1.0.0` (major — the
+initial release). Creates the Gitea release. Deletes all milestone
+branches.
+
+## Coverage (init estimate — refined by PLAN)
+
+| REQ-IDs | Phase |
+|---------|-------|
+| (none — P0 is pre-execution) | 0 |
+| REQ-01..06, 23..28 | 1 |
+| REQ-07..09, 25..26 | 2 |
+| REQ-10..11 | 3 |
+| REQ-12, 14..19 | 4 |
+| REQ-20..22, 29..38 | 5 |
+| (final review, no new REQs) | 6 |
+
+> REQ-13 (`modules/README.md`) lands in phase 3 alongside the primitives.
@@ -0,0 +1,308 @@
+{
+  "active_project": "nova-platform",
+  "active_milestone": "v1.0",
+  "autonomy": {
+    "level": "supervised",
+    "escalation_hooks": [
+      "deploy",
+      "delete_data",
+      "merge_to_main",
+      "verification_failure",
+      "ship"
+    ],
+    "clarify_budget": 10,
+    "decision_confidence_threshold": 0.75,
+    "max_revision_iterations": 2,
+    "max_verification_retries": 2,
+    "escalation_timeout_ms": 300000
+  },
+  "model_profile": "quality",
+  "parallelization": {
+    "enabled": true,
+    "max_concurrent_agents": 5,
+    "min_plans_for_parallel": 2,
+    "max_concurrent_projects": 3
+  },
+  "verification": {
+    "automated_only": true,
+    "escalate_visual": true,
+    "escalate_external_integration": true,
+    "test_first": false
+  },
+  "security": {
+    "auto_accept_low_severity": true,
+    "auto_mitigate_medium_severity": true,
+    "escalate_high_severity": true,
+    "bash_allowlist": {
+      "allowed_commands": [
+        "git",
+        "ls",
+        "cat",
+        "head",
+        "tail",
+        "wc",
+        "echo",
+        "mkdir",
+        "cp",
+        "mv",
+        "rm",
+        "touch",
+        "pwd",
+        "which",
+        "env",
+        "printenv",
+        "python3",
+        "pytest",
+        "pip",
+        "terraform",
+        "curl",
+        "wget",
+        "docker",
+        "docker-compose"
+      ],
+      "max_output_bytes": 1048576,
+      "timeout_ms": 30000,
+      "blocked_env_vars": [
+        "HOME",
+        "PATH",
+        "USER",
+        "SHELL",
+        "AWS_*",
+        "*_TOKEN",
+        "*_KEY",
+        "*_SECRET",
+        "*_PASSWORD",
+        "*_CREDENTIAL",
+        "GITHUB_TOKEN",
+        "GITHUB_API_KEY",
+        "OPENAI_API_KEY",
+        "ANTHROPIC_API_KEY",
+        "OLLAMA_CLOUD_API_KEY",
+        "NOVA_FORGE_TOKEN"
+      ]
+    }
+  },
+  "git": {
+    "branching_strategy": "phase",
+    "auto_commit": true,
+    "auto_push": true
+  },
+  "secrets": {
+    "sources": [
+      ".env",
+      ".env.secrets",
+      ".env.*"
+    ],
+    "disallow": [
+      "shell_env",
+      "netrc",
+      "keychain",
+      "rc_files",
+      "global_config"
+    ],
+    "scopes": {
+      "forge": "NOVA_FORGE_TOKEN",
+      "gitea": "NOVA_FORGE_TOKEN",
+      "github": "GITHUB_TOKEN",
+      "gitlab": "GITLAB_TOKEN",
+      "openai": "OPENAI_API_KEY",
+      "anthropic": "ANTHROPIC_API_KEY",
+      "ollama_cloud": "OLLAMA_CLOUD_API_KEY"
+    }
+  },
+  "release": {
+    "forge": "gitea",
+    "gitea": {
+      "base_url": "https://git.cloudinit.dev",
+      "owner": "continuous-intelligence",
+      "repo": "nova-platform",
+      "token_scope": "gitea"
+    },
+    "github": {
+      "owner": "",
+      "repo": "",
+      "token_scope": "github"
+    },
+    "gitlab": {
+      "base_url": "",
+      "owner": "",
+      "repo": "",
+      "token_scope": "gitlab"
+    }
+  },
+  "ship": {
+    "per_phase": true,
+    "require_release": true,
+    "allow_skip": false,
+    "confirm_before_ship": true,
+    "max_release_retries": 3,
+    "release_blocking": false
+  },
+  "backend": {
+    "provider": "auto",
+    "agent_backends": {
+      "opencode": {
+        "enabled": true
+      },
+      "codex": {
+        "enabled": true
+      },
+      "claude-code": {
+        "enabled": true
+      },
+      "hermes": {
+        "enabled": true
+      }
+    },
+    "llm_backends": {
+      "openai": {
+        "base_url": "https://api.openai.com/v1",
+        "api_key_env": "OPENAI_API_KEY",
+        "model": "gpt-4o",
+        "model_profile": "quality",
+        "timeout_ms": 60000
+      },
+      "ollama-local": {
+        "base_url": "http://localhost:11434",
+        "model_profile": "balanced"
+      },
+      "ollama-cloud": {
+        "base_url": "",
+        "api_key_env": "OLLAMA_CLOUD_API_KEY",
+        "model_profile": "quality",
+        "timeout_ms": 60000
+      },
+      "anthropic": {
+        "base_url": "https://api.anthropic.com",
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "model": "claude-sonnet-4-20250514",
+        "api_version": "2023-06-01",
+        "model_profile": "quality",
+        "timeout_ms": 60000
+      }
+    }
+  },
+  "ideation": {
+    "enabled": true,
+    "categories": [
+      "quality",
+      "architecture",
+      "coverage",
+      "improvement"
+    ],
+    "confidence_threshold": 0.6,
+    "max_ideas": 20,
+    "external_signals": {
+      "npm_audit": true,
+      "osv_advisories": true,
+      "dependency_staleness": true
+    },
+    "cross_project": {
+      "enabled": false,
+      "similarity_weight": 0.5
+    },
+    "chaos": {
+      "enabled": true,
+      "scenarios": [
+        "backend_unavailable",
+        "requirement_change",
+        "test_coverage_drop"
+      ]
+    }
+  },
+  "sessions": {
+    "max_concurrent_sessions": 3,
+    "session_timeout_ms": 3600000,
+    "session_isolation": "branch"
+  },
+  "personas": {
+    "enabled": true,
+    "territory_enforcement": "warn",
+    "personas": [
+      {
+        "name": "lead-developer",
+        "domain": "coordination",
+        "frameworks": [],
+        "constraints": [
+          "pragmatic",
+          "battle-tested defaults"
+        ],
+        "territory": []
+      },
+      {
+        "name": "data-engineer",
+        "domain": "data",
+        "frameworks": [
+          "terraform"
+        ],
+        "constraints": [
+          "schema-first",
+          "type-safe",
+          "migration-driven"
+        ],
+        "territory": [
+          "**/terraform/**",
+          "**/modules/**",
+          "**/schemas/**",
+          "**/*.tf",
+          "**/*.tf.json",
+          "**/*.json"
+        ]
+      },
+      {
+        "name": "backend-engineer",
+        "domain": "backend",
+        "frameworks": [
+          "python",
+          "fastapi"
+        ],
+        "constraints": [
+          "api-first",
+          "strict-typing",
+          "dependency-injection"
+        ],
+        "territory": [
+          "**/core/**",
+          "**/scripts/**",
+          "**/adapters/**",
+          "**/contracts/**",
+          "**/tests/**",
+          "**/*.py"
+        ]
+      },
+      {
+        "name": "frontend-engineer",
+        "domain": "frontend",
+        "active": false,
+        "frameworks": [
+          "react",
+          "next.js"
+        ],
+        "constraints": [
+          "component-first",
+          "server-components",
+          "minimal-client-js"
+        ],
+        "territory": [
+          "**/components/**",
+          "**/pages/**",
+          "**/hooks/**",
+          "**/styles/**",
+          "**/*.tsx",
+          "**/*.css",
+          "**/*.vue"
+        ],
+        "reason": "Nova Platform has no frontend. Deactivated."
+      }
+    ]
+  },
+  "logging": {
+    "level": "info",
+    "format": "json",
+    "file": ".ciagent/logs/ciagent.jsonl"
+  },
+  "telemetry": {
+    "enabled": true,
+    "persist": true
+  }
+}
@@ -0,0 +1,35 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+.env.*
+state.json
+audit.json
+*.tmp
+.DS_Store
+runner-data/
+.env.secrets
+terraform/bootstrap/.bootstrap_state.json
+
+# CIAgent runtime artifacts
+.ciagent/logs/
+
+# Terraform — recursively ignore .terraform dirs, lock files, plans, and state
+**/.terraform/
+**/.terraform.lock.hcl
+**/tfplan
+**/*.tfstate*
+
+# Credential patterns
+*.pem
+*.key
+*.p12
+*.pfx
+*.cer
+*.crt
+*.jks
+*.keystore
+
+.coverage
+.venv/
+nova_platform.egg-info/
@@ -0,0 +1,9 @@
+id: msvc
+name: Microservice
+environment: dev
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
@@ -0,0 +1,9 @@
+id: msvc
+name: Microservice
+environment: dr
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
@@ -0,0 +1,9 @@
+id: msvc
+name: Microservice
+environment: prod
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
@@ -0,0 +1,9 @@
+id: msvc
+name: Microservice
+environment: qa
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
@@ -0,0 +1,9 @@
+id: msvc
+name: Microservice
+environment: dev
+infrastructure:
+  - module: microservice
+    version: "1.0.0"
+    inputs:
+      service_name: "${env.environment}-${contract.id}-svc"
+      desired_count: 2
@@ -0,0 +1,9 @@
+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
@@ -0,0 +1,9 @@
+id: stsi
+name: Static Assets Site
+environment: dr
+infrastructure:
+  - module: static-assets
+    version: "1.0.0"
+    inputs:
+      bucket_name: "${env.environment}-${contract.id}-assets"
+      index_document: index.html
@@ -0,0 +1,9 @@
+id: stsi
+name: Static Assets Site
+environment: prod
+infrastructure:
+  - module: static-assets
+    version: "1.0.0"
+    inputs:
+      bucket_name: "${env.environment}-${contract.id}-assets"
+      index_document: index.html
@@ -0,0 +1,9 @@
+id: stsi
+name: Static Assets Site
+environment: qa
+infrastructure:
+  - module: static-assets
+    version: "1.0.0"
+    inputs:
+      bucket_name: "${env.environment}-${contract.id}-assets"
+      index_document: index.html
@@ -0,0 +1,9 @@
+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
@@ -0,0 +1,180 @@
+"""Nova Platform — Contract Resolver.
+
+Resolves a validated consumer contract to a Stack instance (a flat dict
+conforming to schemas/stack.schema.json).
+
+Flow:
+  1. Validate the contract dict against schemas/contract.schema.json.
+  2. Load the environment via core.environment_check.check().
+  3. Build an interpolation context {'env': env, 'contract': contract}.
+  4. For each infrastructure entry: look up the module + version in the
+     registry, interpolate ${env.*} / ${contract.*} tokens in inputs,
+     and emit a flat stack resource {module, version, inputs}.
+  5. Return the stack dict.
+
+Engine-agnostic: no aws_*, no Terraform terms, no module paths. The stack
+carries NO 'source' field (D-037/C-1 grill fix) — the adapter loads the
+registry to map module -> terraform_dir. L2 is opaque (D-012): a single
+stack resource, no children/wires expansion.
+"""
+
+import json
+import re
+from pathlib import Path
+
+import jsonschema
+import yaml
+
+_TOKEN_RE = re.compile(r"\$\{([a-zA-Z_][a-zA-Z0-9_.]*)\}")
+
+
+class ModuleNotFoundError(KeyError):
+    """Raised when a contract references a module not in the registry."""
+
+
+class VersionNotFoundError(KeyError):
+    """Raised when a contract references a version not in the registry."""
+
+
+def _lookup_dotted(context, dotted):
+    parts = dotted.split(".")
+    cur = context
+    for part in parts:
+        if isinstance(cur, dict) and part in cur:
+            cur = cur[part]
+        else:
+            raise KeyError(dotted)
+    return cur
+
+
+def _expand_vars(value, context):
+    if isinstance(value, str):
+        def _replace(match):
+            token = match.group(1)
+            try:
+                resolved = _lookup_dotted(context, token)
+            except KeyError:
+                raise ValueError(f"unresolved interpolation token: ${{{token}}}")
+            if isinstance(resolved, (dict, list)):
+                return json.dumps(resolved)
+            return str(resolved)
+        return _TOKEN_RE.sub(_replace, value)
+    if isinstance(value, dict):
+        return {k: _expand_vars(v, context) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_vars(v, context) for v in value]
+    return value
+
+
+def _latest_version(registry, module_name):
+    versions = registry[module_name]
+    non_deprecated = [(v, e) for v, e in versions.items()
+                      if not e.get("deprecated", False)]
+    if not non_deprecated:
+        non_deprecated = list(versions.items())
+    non_deprecated.sort(key=lambda x: [int(p) for p in x[0].split(".")],
+                        reverse=True)
+    return non_deprecated[0][0]
+
+
+def _load_schema(path):
+    with open(path) as fh:
+        return json.load(fh)
+
+
+def resolve(contract, registry, modules_dir, environments_dir=None,
+            repo_root=None):
+    """Resolve a validated contract dict to a flat Stack dict.
+
+    Args:
+        contract: validated contract dict (must conform to
+            schemas/contract.schema.json).
+        registry: modules/registry.json loaded as a dict.
+        modules_dir: Path to the modules/ directory (unused for L2-opaque
+            resolution but kept per D-011 for future interface.json reads).
+        environments_dir: Path to core/environments/. If None, derived from
+            repo_root / 'core' / 'environments'.
+        repo_root: Path to the repo root. If None, derived from modules_dir
+            parent's parent (modules_dir is <root>/modules).
+
+    Returns:
+        A flat stack dict conforming to schemas/stack.schema.json:
+        {contract_id, contract_name, environment, resources: [{module,
+        version, inputs}]}.
+
+    Raises:
+        ModuleNotFoundError: contract references an unknown module.
+        VersionNotFoundError: contract references an unknown version.
+        jsonschema.ValidationError: contract does not conform to schema.
+        ValueError: unresolved interpolation token.
+    """
+    if repo_root is None:
+        repo_root = Path(modules_dir).parent.parent
+    if environments_dir is None:
+        environments_dir = Path(repo_root) / "core" / "environments"
+
+    contract_schema_path = Path(repo_root) / "schemas" / "contract.schema.json"
+    contract_schema = _load_schema(contract_schema_path)
+    jsonschema.validate(contract, contract_schema)
+
+    from core import environment_check
+    env = environment_check.check(contract["environment"], environments_dir)
+    # Expose 'environment' as an alias for the env's 'name' field so
+    # ${env.environment} resolves (the env JSON uses 'name', but contracts
+    # reference the environment by ${env.environment}).
+    env["environment"] = env.get("name", contract["environment"])
+
+    context = {"env": env, "contract": contract}
+
+    resources = []
+    for item in contract["infrastructure"]:
+        module_name = item["module"]
+        if module_name not in registry:
+            raise ModuleNotFoundError(module_name)
+        version = item.get("version")
+        if version is None:
+            version = _latest_version(registry, module_name)
+        elif version not in registry[module_name]:
+            raise VersionNotFoundError(f"{module_name}@{version}")
+        inputs = _expand_vars(item.get("inputs", {}), context)
+        resources.append({
+            "module": module_name,
+            "version": version,
+            "inputs": inputs,
+        })
+
+    return {
+        "contract_id": contract["id"],
+        "contract_name": contract["name"],
+        "environment": contract["environment"],
+        "resources": resources,
+    }
+
+
+def main(argv=None):
+    import sys
+    argv = argv or sys.argv[1:]
+    if len(argv) < 2:
+        print("usage: contract_resolver.py <contract.yaml> [out.json]",
+              file=sys.stderr)
+        return 2
+    contract_path = argv[0]
+    out_path = argv[1] if len(argv) > 1 else None
+    repo_root = Path(__file__).resolve().parent.parent
+    with open(contract_path) as fh:
+        contract = yaml.safe_load(fh)
+    with open(repo_root / "modules" / "registry.json") as fh:
+        registry = json.load(fh)
+    stack = resolve(contract, registry, repo_root / "modules",
+                    repo_root=repo_root)
+    if out_path:
+        with open(out_path, "w") as fh:
+            json.dump(stack, fh, indent=2)
+    else:
+        print(json.dumps(stack, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())
@@ -0,0 +1,37 @@
+"""Nova Platform — Environment Check.
+
+Loads and validates a platform-managed environment JSON file.
+
+Simplified per D-019: check(env_name, environments_dir) -> dict, raises
+EnvironmentNotFoundError on missing env. Drops the reference's
+(ok, message) tuple, _onboarding_message, and main() CLI.
+"""
+
+import json
+from pathlib import Path
+
+
+class EnvironmentNotFoundError(FileNotFoundError):
+    """Raised when a named environment has no JSON file."""
+
+
+def check(env_name, environments_dir):
+    """Load and return the environment dict for env_name.
+
+    Args:
+        env_name: environment name (dev, qa, prod, dr).
+        environments_dir: Path to the core/environments/ directory.
+
+    Returns:
+        The parsed environment dict.
+
+    Raises:
+        EnvironmentNotFoundError: no <env_name>.json in environments_dir.
+    """
+    env_path = Path(environments_dir) / f"{env_name}.json"
+    if not env_path.exists():
+        raise EnvironmentNotFoundError(
+            f"environment '{env_name}' not found at {env_path}")
+    with open(env_path) as fh:
+        env = json.load(fh)
+    return env
@@ -0,0 +1,14 @@
+{
+  "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"]
+  }
+}
@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nova.cloudinit.dev/schemas/contract.schema.json",
+  "title": "Nova Consumer Contract",
+  "description": "A consumer's declaration of infrastructure intent. Engine-agnostic: no aws_* or Terraform terms.",
+  "type": "object",
+  "required": ["id", "name", "environment", "infrastructure"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{2,5}$",
+      "description": "Stable operational acronym (3-6 chars). Used in state keys + resource naming."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Human-readable contract name."
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["dev", "qa", "prod", "dr"],
+      "description": "Target environment."
+    },
+    "infrastructure": {
+      "type": "array",
+      "minItems": 1,
+      "description": "List of modules to deploy. Array (not map) per D-015.",
+      "items": {
+        "type": "object",
+        "required": ["module", "inputs"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Module name from the registry."
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+$",
+            "description": "Semver version. Optional — defaults to latest non-deprecated."
+          },
+          "inputs": {
+            "type": "object",
+            "description": "Module-specific inputs. No aws_* keys (engine-agnostic)."
+          }
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nova.cloudinit.dev/schemas/environment.schema.json",
+  "title": "Nova Platform-Managed Environment",
+  "description": "Environment record. Simplified per D-017/D-018 (drops runner_role_arn/autonomy/confidence_threshold — OOS).",
+  "type": "object",
+  "required": ["name", "account_id", "region", "state_backend", "network"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Environment name (dev, qa, prod, dr)."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional human-readable description."
+    },
+    "account_id": {
+      "type": "string",
+      "pattern": "^[0-9]{12}$",
+      "description": "12-digit AWS account ID. Placeholder 000000000000 allowed for offline/dev."
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region (e.g. us-east-1)."
+    },
+    "state_backend": {
+      "type": "object",
+      "required": ["bucket", "lock_table"],
+      "additionalProperties": false,
+      "properties": {
+        "bucket": {
+          "type": "string",
+          "description": "S3 state bucket name."
+        },
+        "lock_table": {
+          "type": "string",
+          "description": "DynamoDB lock table name."
+        }
+      }
+    },
+    "network": {
+      "type": "object",
+      "required": ["vpc_cidr", "azs"],
+      "additionalProperties": false,
+      "properties": {
+        "vpc_cidr": {
+          "type": "string",
+          "description": "VPC CIDR block."
+        },
+        "azs": {
+          "type": "array",
+          "maxItems": 6,
+          "items": {"type": "string"},
+          "description": "Availability zones."
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nova.cloudinit.dev/schemas/stack.schema.json",
+  "title": "Nova Target Stack",
+  "description": "Resolved stack instance. Engine-agnostic: no source/Terraform paths, no aws_* terms (per D-037/C-1 — the adapter loads the registry to resolve module → terraform_dir).",
+  "type": "object",
+  "required": ["contract_id", "contract_name", "environment", "resources"],
+  "additionalProperties": false,
+  "properties": {
+    "contract_id": {
+      "type": "string",
+      "description": "Echoed from the contract."
+    },
+    "contract_name": {
+      "type": "string",
+      "description": "Echoed from the contract."
+    },
+    "environment": {
+      "type": "string",
+      "enum": ["dev", "qa", "prod", "dr"],
+      "description": "Echoed from the contract."
+    },
+    "resources": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One entry per contract infrastructure item. Flat per D-012 (L2 is opaque — no children/wires expansion).",
+      "items": {
+        "type": "object",
+        "required": ["module", "version", "inputs"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "description": "Module name."
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+$",
+            "description": "Resolved semver version."
+          },
+          "inputs": {
+            "type": "object",
+            "description": "Interpolated module inputs."
+          }
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,61 @@
+"""Pytest fixtures for nova-platform tests."""
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+
+@pytest.fixture
+def repo_root():
+    return ROOT
+
+
+@pytest.fixture
+def registry():
+    """Minimal registry fixture for resolver/adapter tests (P3 lands the real one)."""
+    return {
+        "static-assets": {
+            "1.0.0": {
+                "interface": "modules/l2/static-assets/interface.json",
+                "terraform_dir": "modules/l2/static-assets/terraform",
+                "published_at": "2026-08-20T00:00:00Z",
+                "deprecated": False,
+                "kind": "l2",
+            }
+        },
+        "microservice": {
+            "1.0.0": {
+                "interface": "modules/l2/microservice/interface.json",
+                "terraform_dir": "modules/l2/microservice/terraform",
+                "published_at": "2026-08-20T00:00:00Z",
+                "deprecated": False,
+                "kind": "l2",
+            }
+        },
+        "s3": {
+            "1.0.0": {
+                "interface": "modules/l1/s3/interface.json",
+                "terraform_dir": "modules/l1/s3/terraform",
+                "published_at": "2026-08-20T00:00:00Z",
+                "deprecated": False,
+                "kind": "l1",
+            }
+        },
+    }
+
+
+@pytest.fixture
+def contract_schema():
+    with open(ROOT / "schemas" / "contract.schema.json") as fh:
+        return json.load(fh)
+
+
+@pytest.fixture
+def stack_schema():
+    with open(ROOT / "schemas" / "stack.schema.json") as fh:
+        return json.load(fh)
@@ -0,0 +1,118 @@
+"""Tests for core/contract_resolver.py — REQ-23."""
+
+import json
+from pathlib import Path
+
+import jsonschema
+import pytest
+
+from core.contract_resolver import (
+    resolve,
+    ModuleNotFoundError,
+    VersionNotFoundError,
+)
+
+
+def _contract(infra=None, env="dev", cid="stsi", name="Test"):
+    return {
+        "id": cid,
+        "name": name,
+        "environment": env,
+        "infrastructure": infra if infra is not None else [
+            {"module": "static-assets", "version": "1.0.0",
+             "inputs": {"bucket_name": "test-bucket", "index_document": "index.html"}},
+        ],
+    }
+
+
+class TestResolveHappyPath:
+    def test_resolves_static_assets(self, registry, repo_root):
+        contract = _contract()
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        assert stack["contract_id"] == "stsi"
+        assert stack["contract_name"] == "Test"
+        assert stack["environment"] == "dev"
+        assert len(stack["resources"]) == 1
+        r = stack["resources"][0]
+        assert r["module"] == "static-assets"
+        assert r["version"] == "1.0.0"
+        assert r["inputs"]["bucket_name"] == "test-bucket"
+
+    def test_stack_validates_against_schema(self, registry, repo_root, stack_schema):
+        contract = _contract()
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        jsonschema.validate(stack, stack_schema)
+
+    def test_no_source_field(self, registry, repo_root):
+        contract = _contract()
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        assert "source" not in stack["resources"][0]
+
+
+class TestResolveInterpolation:
+    def test_env_token_expanded(self, registry, repo_root):
+        contract = _contract(infra=[
+            {"module": "static-assets", "version": "1.0.0",
+             "inputs": {"bucket_name": "${env.environment}-${contract.id}-assets",
+                        "index_document": "index.html"}},
+        ])
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        assert stack["resources"][0]["inputs"]["bucket_name"] == "dev-stsi-assets"
+
+    def test_env_dotted_token(self, registry, repo_root):
+        contract = _contract(infra=[
+            {"module": "static-assets", "version": "1.0.0",
+             "inputs": {"bucket_name": "${env.region}-bucket",
+                        "index_document": "index.html"}},
+        ])
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        assert stack["resources"][0]["inputs"]["bucket_name"] == "us-east-1-bucket"
+
+    def test_unresolved_token_raises(self, registry, repo_root):
+        contract = _contract(infra=[
+            {"module": "static-assets", "version": "1.0.0",
+             "inputs": {"bucket_name": "${env.nonexistent}-bucket",
+                        "index_document": "index.html"}},
+        ])
+        with pytest.raises(ValueError, match="unresolved interpolation token"):
+            resolve(contract, registry, repo_root / "modules", repo_root=repo_root)
+
+
+class TestResolveVersioning:
+    def test_version_defaults_to_latest(self, registry, repo_root):
+        contract = _contract(infra=[
+            {"module": "static-assets", "inputs": {"bucket_name": "b",
+              "index_document": "index.html"}},
+        ])
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        assert stack["resources"][0]["version"] == "1.0.0"
+
+
+class TestResolveErrors:
+    def test_unknown_module(self, registry, repo_root):
+        contract = _contract(infra=[
+            {"module": "nope", "version": "1.0.0",
+             "inputs": {"x": "y"}},
+        ])
+        with pytest.raises(ModuleNotFoundError):
+            resolve(contract, registry, repo_root / "modules", repo_root=repo_root)
+
+    def test_unknown_version(self, registry, repo_root):
+        contract = _contract(infra=[
+            {"module": "static-assets", "version": "9.9.9",
+             "inputs": {"bucket_name": "b", "index_document": "index.html"}},
+        ])
+        with pytest.raises(VersionNotFoundError):
+            resolve(contract, registry, repo_root / "modules", repo_root=repo_root)
+
+    def test_invalid_contract_missing_id(self, registry, repo_root):
+        contract = {"name": "Test", "environment": "dev",
+                     "infrastructure": [{"module": "s3", "inputs": {}}]}
+        with pytest.raises(jsonschema.ValidationError):
+            resolve(contract, registry, repo_root / "modules", repo_root=repo_root)
@@ -0,0 +1,60 @@
+"""Tests for schemas/contract.schema.json — REQ-27.
+
+Validates all 10 sample contracts against the contract schema.
+"""
+
+import glob
+
+import jsonschema
+import pytest
+import yaml
+
+from tests.conftest import ROOT
+
+
+SAMPLE_CONTRACTS = sorted(glob.glob(str(ROOT / "contracts" / "*.yml")))
+
+
+class TestSampleContracts:
+    @pytest.mark.parametrize("path", SAMPLE_CONTRACTS,
+                             ids=[p.split("/")[-1] for p in SAMPLE_CONTRACTS])
+    def test_validates(self, path, contract_schema):
+        with open(path) as fh:
+            contract = yaml.safe_load(fh)
+        jsonschema.validate(contract, contract_schema)
+
+
+class TestSchemaNegativeCases:
+    def _validate(self, instance, schema):
+        jsonschema.validate(instance, schema)
+
+    def test_missing_id_rejected(self, contract_schema):
+        with pytest.raises(jsonschema.ValidationError):
+            self._validate({"name": "X", "environment": "dev",
+                             "infrastructure": []}, contract_schema)
+
+    def test_bad_id_pattern_rejected(self, contract_schema):
+        with pytest.raises(jsonschema.ValidationError):
+            self._validate({"id": "UPPER", "name": "X", "environment": "dev",
+                            "infrastructure": []}, contract_schema)
+
+    def test_bad_environment_rejected(self, contract_schema):
+        with pytest.raises(jsonschema.ValidationError):
+            self._validate({"id": "abc", "name": "X", "environment": "staging",
+                            "infrastructure": []}, contract_schema)
+
+    def test_empty_infrastructure_rejected(self, contract_schema):
+        with pytest.raises(jsonschema.ValidationError):
+            self._validate({"id": "abc", "name": "X", "environment": "dev",
+                            "infrastructure": []}, contract_schema)
+
+    def test_infrastructure_missing_module_rejected(self, contract_schema):
+        with pytest.raises(jsonschema.ValidationError):
+            self._validate({"id": "abc", "name": "X", "environment": "dev",
+                            "infrastructure": [{"inputs": {}}]}, contract_schema)
+
+    def test_additional_top_level_rejected(self, contract_schema):
+        with pytest.raises(jsonschema.ValidationError):
+            self._validate({"id": "abc", "name": "X", "environment": "dev",
+                            "infrastructure": [{"module": "s3", "inputs": {}}],
+                            "extra": True}, contract_schema)
@@ -0,0 +1,34 @@
+"""Tests for core/environment_check.py — REQ-24."""
+
+from pathlib import Path
+
+import pytest
+
+from core.environment_check import check, EnvironmentNotFoundError
+
+
+class TestCheckHappyPath:
+    def test_dev_returns_dict(self, repo_root):
+        env = check("dev", repo_root / "core" / "environments")
+        assert env["name"] == "dev"
+        assert env["region"] == "us-east-1"
+        assert env["state_backend"]["bucket"] == "nova-tfstate-dev-us-east-1"
+        assert env["state_backend"]["lock_table"] == "nova-tfstate-locks"
+
+    def test_returns_all_required_fields(self, repo_root):
+        env = check("dev", repo_root / "core" / "environments")
+        for f in ("name", "account_id", "region", "state_backend", "network"):
+            assert f in env, f"missing {f}"
+
+
+class TestCheckErrors:
+    def test_missing_env_raises(self, repo_root, tmp_path):
+        with pytest.raises(EnvironmentNotFoundError):
+            check("nonexistent", tmp_path)
+
+    def test_missing_env_message_names_env(self, repo_root, tmp_path):
+        try:
+            check("qa", tmp_path)
+            assert False, "should have raised"
+        except EnvironmentNotFoundError as e:
+            assert "qa" in str(e)
@@ -0,0 +1,70 @@
+"""Tests for schemas/stack.schema.json — REQ-28.
+
+Validates resolved stacks against the stack schema. Builds stacks via
+resolve() using a registry fixture.
+"""
+
+import jsonschema
+import pytest
+
+from core.contract_resolver import resolve
+
+
+def _contract():
+    return {
+        "id": "stsi",
+        "name": "Test",
+        "environment": "dev",
+        "infrastructure": [
+            {"module": "static-assets", "version": "1.0.0",
+             "inputs": {"bucket_name": "test-bucket", "index_document": "index.html"}},
+        ],
+    }
+
+
+class TestStackSchema:
+    def test_resolved_stack_validates(self, registry, repo_root, stack_schema):
+        stack = resolve(_contract(), registry, repo_root / "modules",
+                        repo_root=repo_root)
+        jsonschema.validate(stack, stack_schema)
+
+    def test_multi_resource_stack_validates(self, registry, repo_root, stack_schema):
+        contract = {
+            "id": "stsi", "name": "Test", "environment": "dev",
+            "infrastructure": [
+                {"module": "static-assets", "version": "1.0.0",
+                 "inputs": {"bucket_name": "b1", "index_document": "index.html"}},
+                {"module": "microservice", "version": "1.0.0",
+                 "inputs": {"service_name": "s1", "desired_count": 2}},
+            ],
+        }
+        stack = resolve(contract, registry, repo_root / "modules",
+                        repo_root=repo_root)
+        assert len(stack["resources"]) == 2
+        jsonschema.validate(stack, stack_schema)
+
+
+class TestStackSchemaNegative:
+    def test_missing_resources_rejected(self, stack_schema):
+        bad = {"contract_id": "x", "contract_name": "X", "environment": "dev"}
+        with pytest.raises(jsonschema.ValidationError):
+            jsonschema.validate(bad, stack_schema)
+
+    def test_empty_resources_rejected(self, stack_schema):
+        bad = {"contract_id": "x", "contract_name": "X", "environment": "dev",
+               "resources": []}
+        with pytest.raises(jsonschema.ValidationError):
+            jsonschema.validate(bad, stack_schema)
+
+    def test_resource_missing_module_rejected(self, stack_schema):
+        bad = {"contract_id": "x", "contract_name": "X", "environment": "dev",
+               "resources": [{"version": "1.0.0", "inputs": {}}]}
+        with pytest.raises(jsonschema.ValidationError):
+            jsonschema.validate(bad, stack_schema)
+
+    def test_resource_extra_source_rejected(self, stack_schema):
+        bad = {"contract_id": "x", "contract_name": "X", "environment": "dev",
+               "resources": [{"module": "s3", "version": "1.0.0", "inputs": {},
+                              "source": "modules/l1/s3/terraform"}]}
+        with pytest.raises(jsonschema.ValidationError):
+            jsonschema.validate(bad, stack_schema)