nova-platform/.ciagent/REQUIREMENTS.md

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