Merge branch 'main' into phase/00-pre-execution

.gitea/workflows/ci.yml

@@ -0,0 +1,78 @@
+# nova-platform CI — offline mirror of scripts/run_ci.sh (task order coreci/nova-platform#3, hip c12363)
+#
+# Stages mirror the local CI script: lint (py_compile) -> test (pytest,
+# not shell markers) -> check-only (run_platform.sh --check-only).
+# Every leg either runs for real or fails loud with its reason — no leg
+# is skipped silently and nothing skipped is presented as passed.
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "fetch (probe: stock actions/checkout@v4)"
+        id: actfetch
+        continue-on-error: true
+        uses: actions/checkout@v4
+      - name: fetch (git-clone fallback, run token)
+        if: ${{ steps.actfetch.outcome == 'failure' }}
+        run: |
+          set -euo pipefail
+          REF="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
+          git clone --depth 1 -b "$REF" "https://coreci-nova-po:${{ secrets.GITEA_TOKEN }}@git.coreci.dev/${{ github.repository }}.git" .
+      - name: toolchain probe (reports; never gates)
+        run: |
+          set -u
+          python3 --version
+          python3 -m pytest --version 2>/dev/null || echo "pytest: ABSENT"
+          for m in yaml jsonschema boto3 moto; do
+            python3 -c "import $m" 2>/dev/null && echo "$m: OK" || echo "$m: ABSENT"
+          done
+          timeout 25 pip download --no-deps --dest /tmp/piptest pytest >/dev/null 2>&1 && echo "pypi: REACHABLE" || echo "pypi: UNREACHABLE"
+      - name: deps (requirements-test.txt when pypi reachable)
+        run: |
+          if timeout 25 pip download --no-deps --dest /tmp/piptest pytest >/dev/null 2>&1; then
+            pip install -q -r requirements-test.txt && echo "deps: installed from requirements-test.txt"
+          else
+            echo "deps: pypi UNREACHABLE - proceeding on the runner's preinstalled toolchain only"
+          fi
+      - name: lint (stage 1/3 - py_compile, stdlib-only)
+        run: |
+          set -euo pipefail
+          python3 -m py_compile $(find core/ adapters/ scripts/ -name '*.py' -not -path '*/__pycache__/*')
+          echo "lint: OK"
+      - name: test (stage 2/3 - pytest, offline markers)
+        run: |
+          set -euo pipefail
+          MISSING=""
+          python3 -m pytest --version >/dev/null 2>&1 || MISSING="$MISSING pytest"
+          for m in yaml jsonschema boto3 moto; do
+            python3 -c "import $m" 2>/dev/null || MISSING="$MISSING $m"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "FAIL: test leg cannot run - toolchain absent on runner vantage:$MISSING" >&2
+            exit 1
+          fi
+          python3 -m pytest tests/ -q --tb=short -m "not shell"
+          echo "test: OK"
+      - name: check-only (stage 3/3 - run_platform.sh --check-only)
+        run: |
+          set -euo pipefail
+          MISSING=""
+          for m in yaml jsonschema; do
+            python3 -c "import $m" 2>/dev/null || MISSING="$MISSING $m"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "FAIL: check-only leg cannot run - toolchain absent on runner vantage:$MISSING" >&2
+            exit 1
+          fi
+          bash scripts/run_platform.sh --check-only contracts/static-assets.yml
+          echo "check-only: OK"
+      - name: summary
+        run: 'echo "=== CI stages complete: lint, test, check-only ==="'

README.md

@@ -5,6 +5,29 @@
 > it through the Terraform adapter, and applies it. Every deployment is
 > reproducible from the shell, not just in CI.
 
+**TL;DR** — Nova Platform turns a small YAML contract into AWS
+infrastructure: declare modules and inputs, and the platform resolves the
+contract, compiles Terraform, and applies it. The last tagged release
+(v0.1.6) predates CoreCI adoption; nothing has shipped under CoreCI yet.
+
+**What** —
+- One contract file per deployment: module names and versions,
+  environment, and module-specific inputs.
+- The platform resolves the contract to a stack, compiles it through the
+  Terraform adapter, and applies it.
+- Offline checks ship in the repo: `bash scripts/run_ci.sh` runs lint,
+  tests, and a check-only pass — no AWS required.
+
+**Why** — Contract-driven deploys are reproducible and auditable; a
+consumer never writes infrastructure code.
+
+**Action** — No action — FYI. Consumers start at
+[`docs/consumer-guide.md`](docs/consumer-guide.md); the product owner is
+coreci-nova-po.
+
+**Details** — Design: [`docs/architecture.md`](docs/architecture.md);
+runbook: "How to run" below.
+
 Nova Platform is the **infrastructure-delivery core** of the Nova model.
 The DevSecOps, identity, audit-ledger, and central CI-pipeline-contract
 machinery of the reference are intentionally removed. What remains: a

docs/ci.md

@@ -0,0 +1,26 @@
+# Continuous integration - nova-platform
+
+**TL;DR -** Every push and every pull request to `main` runs the CI
+workflow (`.gitea/workflows/ci.yml`). It is the offline mirror of
+`scripts/run_ci.sh`: lint, test, check-only. A leg that cannot run fails
+loud - nothing skipped is reported as passed.
+
+**What** -
+
+- **lint** - `python3 -m py_compile` over `core/`, `adapters/`, `scripts/`
+  (stdlib only, always runs).
+- **test** - `pytest tests/ -q -m "not shell"`, with the test dependencies
+  from `requirements-test.txt` installed first when pypi is reachable; a
+  missing toolchain fails the leg with its absence list.
+- **check-only** - `bash scripts/run_platform.sh --check-only
+  contracts/static-assets.yml` (needs `yaml` + `jsonschema`).
+
+**Why** - the line shipped without a pipeline, so every change went out
+ungated. The workflow runs the same three legs as the local script, so a
+green local run and a green pipeline mean the same thing.
+
+**Action** - none - FYI. The pipeline was ordered under
+`coreci/nova-platform#3`; the workflow itself landed in PR #6.
+
+**Details** - local equivalent: `bash scripts/run_ci.sh`. Run history:
+the repository's Actions tab.

docs/consumer-guide.md

@@ -1,5 +1,25 @@
 # Consumer Guide — Declare intent, deploy to AWS
 
+**TL;DR** — This guide takes a consumer from an empty repository to
+applied AWS infrastructure: create a repo, write one YAML contract,
+validate offline, then run the platform script against AWS.
+
+**What** —
+- Step-by-step contract authoring with a worked static-site example,
+  generic across all modules.
+- A field-by-field reference for contract and module inputs.
+- Offline validation first (no AWS); the live AWS run second.
+
+**Why** — The contract is the whole consumer interface; infrastructure
+code stays platform-side.
+
+**Action** — No action — FYI. Follow Steps 1-6 below when ready to
+deploy.
+
+**Details** — The platform README (commands and credentials);
+[`docs/contracts/`](contracts/index.md) (contract shapes).
+
+
 This guide walks a consumer through creating a repo, writing a contract,
 validating it offline, and running it against AWS. It is **generic** across
 all modules in the registry; `static-assets` is the worked example, but

modules/README.md

@@ -1,5 +1,11 @@
 # Nova Modules
 
+**TL;DR** — Nova's module library: two tiers of engine-agnostic modules,
+whose contract is declared in `interface.json` and translated by an adapter
+(Terraform today) to concrete infrastructure. This file explains how
+modules compose and how to add one; the L1/L2 tables and adapter detail
+follow below.
+
 Nova ships a two-tier module library. Modules are **engine-agnostic**:
 their contract is declared in `interface.json` (stack types like
 `aws:s3:bucket`), and an adapter translates the contract to a concrete