# 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).