docs(milestone): complete v1.0-nova-platform (release v0.1.6)
---ci--- project: nova-platform milestone: v1.0 status: complete requirements: covered: [REQ-01,REQ-02,REQ-03,REQ-04,REQ-05,REQ-06,REQ-07,REQ-08,REQ-09,REQ-10,REQ-11,REQ-12,REQ-13,REQ-14,REQ-15,REQ-16,REQ-17,REQ-18,REQ-19,REQ-20,REQ-21,REQ-22,REQ-23,REQ-24,REQ-25,REQ-26,REQ-27,REQ-28,REQ-29,REQ-30,REQ-31,REQ-32,REQ-33,REQ-34,REQ-35,REQ-36,REQ-37,REQ-38] partial: [] ---/ci--- v1.0 milestone complete: simplified infrastructure-delivery platform derived from Nova (acdl). 6 phases (P0-P5 + P6 final). 38 REQ-IDs. 38 decisions (D-001..D-038). 76 tests pass. Engine boundary holds. Happy paths green (check-only + CI). 13 L1 + 2 L2 modules. 5 terraform roots. Shell reproducibility. Zero OOS files. Tags: v0.1.0 (P0) → v0.1.1..v0.1.5 (P1..P5) → v0.1.6 (P6 = milestone release on v0.1 patch line).
This commit is contained in:
CIAgent
@@ -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).
|
||||
Reference in New Issue
Block a user