From a0a658bc9a8d2bccaf3a12ccfac3c7285e236745 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 12 Aug 2026 21:11:51 +0000 Subject: [PATCH] =?UTF-8?q?docs(init):=20validate=20specification=20?= =?UTF-8?q?=E2=80=94=20v1.26=20Live=20Pilot=20Estate=20Activation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ---ci--- project: acdl phase: 0 milestone: v1.26 status: specify projects: [acdl, nova-blockchain-exchange] requirements: [REQ-310..REQ-321] ---/ci--- --- .ciagent/CHECKPOINT.json | 46 ++--- .ciagent/PROJECT.md | 82 ++++++++ .ciagent/ROADMAP.md | 88 +++++++++ .ciagent/config.json | 9 +- .ciagent/nova-blockchain-exchange/PROJECT.md | 92 +++++++++ .../nova-blockchain-exchange/REQUIREMENTS.md | 187 ++++++++++++++++++ .ciagent/nova-blockchain-exchange/ROADMAP.md | 57 ++++++ 7 files changed, 530 insertions(+), 31 deletions(-) create mode 100644 .ciagent/nova-blockchain-exchange/PROJECT.md create mode 100644 .ciagent/nova-blockchain-exchange/REQUIREMENTS.md create mode 100644 .ciagent/nova-blockchain-exchange/ROADMAP.md diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json index 1f6143f..8d7c736 100644 --- a/.ciagent/CHECKPOINT.json +++ b/.ciagent/CHECKPOINT.json @@ -1,33 +1,21 @@ { - "phase": 5, - "stage": "complete", - "milestone": "v1.25", - "phase_role": "final", + "phase": 0, + "stage": "specify", + "milestone": "v1.26", + "phase_role": "pre_execution", "attempts": 0, - "updated_at": "2026-08-12T18:00:00Z", + "updated_at": "2026-08-12T21:11:00Z", "project": "acdl", - "milestone_complete": true, - "tag_line": "v1.24.x", - "tag": "v1.24.5", - "release": { - "forge": "gitea", - "releases_created": true, - "release_ids": { - "v1.24.0": 640, - "v1.24.1": 641, - "v1.24.2": 642, - "v1.24.3": 643, - "v1.24.4": 644, - "v1.24.5": 645 - }, - "milestone_release_id": 645, - "milestone_release_tag": "v1.24.5" - }, - "requirements": ["REQ-291", "REQ-292", "REQ-293", "REQ-294", "REQ-295", "REQ-296", "REQ-297", "REQ-298", "REQ-299", "REQ-300", "REQ-301", "REQ-302", "REQ-303", "REQ-304", "REQ-305", "REQ-306", "REQ-307", "REQ-308", "REQ-309"], - "requirements_covered": 19, - "requirements_partial": 0, - "tests": {"total": 170, "passed": 170, "skipped": 23, "failed": 0, "preexisting_flaky": "test_metrics_emitters.py::test_attestation_event_emission (fails on main, unrelated to v1.25)"}, - "phases": {"P0": "complete", "P1": "complete", "P2": "complete", "P3": "complete", "P4": "complete", "P5": "complete"}, - "review": {"p0_fixed": 1, "p1_fixed": 3, "p1_flagged_posthoc": 2, "escalations": 0}, - "notes": "v1.25 milestone complete. Tag v1.24.5 (milestone release, gitea id 645). 19 requirements complete (REQ-291..309). 6 phases. 170 tests pass (23 skip-without-kj). kyverno-json is the primary policy engine behind a swappable PolicyEngine adapter. Merged milestone/v1.25-kyverno-json to main. All milestone branches deleted. Next milestone starts fresh." + "projects": ["acdl", "nova-blockchain-exchange"], + "active_milestone": "v1.26", + "milestone_branch": "milestone/v1.26-pilot-activation", + "phase_branch": "phase/00-specify-clarify-research-plan", + "tag_line": "v1.25.x", + "requirements": ["REQ-310", "REQ-311", "REQ-312", "REQ-313", "REQ-314", "REQ-315", "REQ-316", "REQ-317", "REQ-318", "REQ-319", "REQ-320", "REQ-321"], + "pre_run": { + "flaky_test_fixed": "8c68d68 test(metrics): fix attestation-event test freshness time-bomb", + "acdl_to_nova_migration": "f844fea chore(bootstrap): migrate ACDL_* env vars to NOVA_*", + "aws_bootstrap": "S3 nova-tfstate-581513795199-us-east-1 + DynamoDB nova-outbox created (idempotent, account 581513795199)", + "consumer_repo_created": "continuous-intelligence/nova-blockchain-exchange (Gitea, private, init)" + } } \ No newline at end of file diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md index c33ecf7..eb56064 100644 --- a/.ciagent/PROJECT.md +++ b/.ciagent/PROJECT.md @@ -1698,3 +1698,85 @@ impl (REQ-293,294), contract policies (REQ-295,296), stack-IR policies (REQ-297,298,299), plan-JSON policies + pipeline wiring (REQ-300,301,302), meta-policies (REQ-303), regression-gate policies (REQ-304,305), docs + adapter README (REQ-306,307), tests (REQ-308,309). + +## v1.26 — Live Pilot Estate Activation (active) + +> **Active milestone.** Feature milestone — the first real consumer +> estate (a stock exchange on a homegrown PoA blockchain, equities +> only) is activated against live AWS account `581513795199`, lifting +> D-096. Branch: `milestone/v1.26-pilot-activation`. Tags run on the +> **v1.25.x** patch line: `v1.25.0` (P0) → `v1.25.1..v1.25.4` (P1–P4) +> → `v1.25.5` (P5 final = milestone release). +> +> **Multi-project mode:** this milestone introduces a 2nd tracked +> project — `nova-blockchain-exchange` (Gitea repo +> `continuous-intelligence/nova-blockchain-exchange`, local clone +> `/root/nova-blockchain-exchange`). The platform repo (`acdl`) remains +> the platform source; the consumer repo owns the app code + +> `contract.yaml`. Both projects share the v1.26 milestone; `.ciagent/` +> paths are per-project (`.ciagent/acdl/` for platform files — note: the +> platform's existing flat `.ciagent/` files remain the primary set for +> v1.26; the consumer's files live in `.ciagent/nova-blockchain-exchange/`). + +### Why + +NORTH_STAR.md has three Post-Pilot targets (Touchless Resolution ≥99%, +Human Escalation <0.1%, AI Decision Accuracy ≥99.5%) whose measurement +*pipeline* is grounded but whose *denominator* is zero — no consumer +estate has ever run. v1.25 shipped the swappable policy engine; v1.26 +ships the first real consumer. The D-096 deferral (live AWS +re-provisioning) is the single blocker; the pre-run (Workstream A) +re-created the state bucket + outbox table, so the platform components +exist. The milestone grounds the metrics (outcome backfill + +escalation reason), wires the env JSON to the real account, and runs +the pilot end-to-end. + +### What the milestone delivers + +- **Homegrown PoA blockchain** (`nova-blockchain-exchange` repo) — + append-only blocks, single validator (pilot), deterministic block + production, T+1 settlement finality = block commit. Equities only + (bonds/derivatives/options deferred). +- **Order-matching engine** — limit order book, price-time priority. +- **Settlement service** — T+1, idempotent, finality = block commit. +- **Consumer `contract.yaml`** — declares the exchange stack; validated + against `schemas/contract.schema.json`; per-env variants. +- **Consumer deploy via `deploy.yml@v1.25`** — the reusable workflow + applies the contract, runs the policy engine, computes the + confidence signal, gates qa/prod/dr with HITL attestation, and records + every decision in the Decision Ledger. +- **3 Post-Pilot metrics grounded** — outcome backfill (AI Decision + Accuracy), `reason='confidence'` escalation tag (Human Escalation + Frequency), and the pilot run itself (Touchless Resolution Rate + denominator activates). +- **3 kyverno-json policies extending v1.25** — settlement-finality + (securities-specific), pilot-readiness (no placeholder account), + and the existing meta-policies (block-on-any-critical, + tagging-rules-agree) apply over the pilot's PCRs. +- **Env-JSON `state_backend` wiring reconciliation** — the adapter + reads `state_backend.bucket` from the env JSON (closing the wiring + gap); the env JSONs are bound to account `581513795199`. + +### Requirements + +New requirements REQ-310..REQ-321 — see +`.ciagent/nova-blockchain-exchange/REQUIREMENTS.md` §v1.26. Summary: +blockchain core (REQ-310), order engine (REQ-311), settlement +(REQ-312), consumer contract (REQ-313), deploy invocation (REQ-314), +settlement-finality policy (REQ-315), pilot regression CAP (REQ-316), +outcome backfill (REQ-317), escalation reason (REQ-318), env-JSON +wiring (REQ-319), pilot-readiness policy (REQ-320), docs (REQ-321). + +### Hard constraints + +- DO NOT lift D-083 (S3 Object Lock/JWS) — stays deferred; the SQLite + hash-chain + DynamoDB outbox is the pilot's audit record. +- DO NOT lift D-126 (hot path) — cold-only metrics are sufficient for + the pilot. +- DO NOT add multi-cloud (Azure/GCP) — Nova is AWS-only this milestone. +- DO NOT add ML forecasting — the Predictive/Reactive metric stays + deferred. +- DO NOT add bonds/derivatives/options — equities only (D-200). +- DO NOT add multi-validator BFT — single validator PoA (D-201). +- The consumer deploy MUST go through `deploy.yml@v1.25` — no direct + `terraform apply` bypassing the platform's gates. diff --git a/.ciagent/ROADMAP.md b/.ciagent/ROADMAP.md index 2398727..365484a 100644 --- a/.ciagent/ROADMAP.md +++ b/.ciagent/ROADMAP.md @@ -2246,3 +2246,91 @@ final). Tags: `v1.24.0` (P0) → `v1.24.5` (P5 = milestone release). (mark v1.25 complete), `NORTH_STAR.md` (note Strategic Objective #2 — provable trust via a replaceable policy-engine substrate). - **Requirements:** REQ-291..309 (19 requirements). + +## v1.26 (active, tag line `v1.25.x`): Live Pilot Estate Activation + +`D-096` lifts. The first real consumer estate — a stock exchange on a +homegrown Proof-of-Authority blockchain (equities only, single +validator, T+1 settlement finality = block commit) — is activated +against live AWS account `581513795199`. The consumer repo +(`nova-blockchain-exchange`) owns the app code + `contract.yaml`; the +platform repo (`acdl`) provides the deploy workflow (`deploy.yml@v1.25`), +the policy engine (kyverno-json, swappable per v1.25), the confidence +signal, and the HITL attestation gates. The milestone grounds the three +Post-Pilot targets in NORTH_STAR.md (Touchless Resolution ≥99%, Human +Escalation <0.1%, AI Decision Accuracy ≥99.5%) — the denominators +activate when the pilot runs. Three kyverno-json policies extend v1.25: +settlement-finality (securities-specific), pilot-readiness (no +placeholder account), and the existing meta-policies (block-on-any- +critical, tagging-rules-agree) apply over the pilot's PCRs. The +env-JSON `state_backend` wiring gap is closed (adapter reads the env +JSON's bucket). Multi-project mode activates (`nova-blockchain-exchange` +is the 2nd tracked project). Pre-run (Workstream A) re-created the S3 +state bucket + DynamoDB outbox table (bootstrap). 12 requirements +(REQ-310..321), 5 phases (P0 pre-execution + 4 execution + 1 final). +Tags: `v1.25.0` (P0) → `v1.25.5` (P5 = milestone release). + +### Phase P1 — blockchain-core (planned, tag v1.25.1) +- REQ-310: `nova-blockchain-exchange` repo — homegrown PoA blockchain + core (`chain/block.py`, `chain/ledger.py`, `chain/validator.py`). + Append-only blocks, single validator, SHA-256 hash chain, + deterministic block production, genesis block. +- REQ-311: Order-matching engine (`engine/order_book.py`, + `engine/order.py`) — limit order book, price-time priority, partial + fills. +- REQ-312: Settlement service (`settlement/service.py`) — T+1, + idempotent, finality = block commit. + +### Phase P2 — consumer-contract-and-deploy (planned, tag v1.25.2) +- REQ-313: `nova-blockchain-exchange/contract.yaml` + per-env variants + (dev/qa/prod) — validated against `schemas/contract.schema.json`. +- REQ-314: `nova-blockchain-exchange/.github/workflows/deploy.yml` + + `.gitea/workflows/deploy.yml` — `uses: acdl/.github/workflows/deploy.yml@v1.25` + with `mode: full`. + +### Phase P3 — pilot-metrics-and-policies (planned, tag v1.25.3) +- REQ-315: `adapters/kyverno-json/policies/settlement-finality.json` — + kyverno-json policy asserting all matches in the promotion window have + committed blocks (securities-specific). +- REQ-316: `core/regression_verify.py` gains CAP-025 + (live-pilot-apply) — the round-trip assertion (contract resolve → + adapter compile → terraform plan → policy scan → confidence signal → + attestation → outbox record) against `581513795199`. +- REQ-317: `core/metrics/outcome_backfill.py` — wire + `apply.completed`/`apply.failed` → `fact_decision.outcome` (grounds AI + Decision Accuracy; today `outcome` is stuck `pending`). +- REQ-318: `core/confidence_signal.py` — `ai.decision.made` gains + `escalation_reason: 'confidence'` when `band == 'block'` (grounds + Human Escalation Frequency numerator). +- REQ-319: `adapters/terraform/adapter.py` — reads + `env.state_backend.bucket` from the env JSON (closing the wiring gap); + `core/environments/*.json` `state_backend.bucket` → + `nova-tfstate-581513795199-us-east-1`. +- REQ-320: `adapters/kyverno-json/policies/pilot-readiness/no-placeholder-account.json` + — declarative gate preventing apply against a placeholder account. + +### Phase P4 — pilot-run-and-docs (planned, tag v1.25.4) +- REQ-321: `adapters/README.md` (new consumer row) + + `docs/METRICS.md` (Post-Pilot metrics grounded note) + + `.ciagent/ARCHITECTURE.md` §12.8 (Pilot Estate) + + `.ciagent/nova-blockchain-exchange/README.md` (onboarding guide). +- Live pilot end-to-end run: `nova-blockchain-exchange` contract → + `deploy.yml@v1.25` mode=full → apply → attest → record against + `581513795199`. The run's `ai.decision.made` + `attestation.recorded` + events land in the Decision Ledger; the regression gate (CAP-025) + verifies the round-trip. + +### Phase P5 — final review + audit + milestone ship (Final Phase, tag v1.25.5) +- Multi-persona code review across P1..P4 (lead-developer, backend- + engineer, data-engineer, policy-engineer, blockchain-engineer). + Auto-fix P0; flag P1+. +- Audit: reconstruction test (git log ↔ `.ciagent/`), branch hygiene, + commit discipline. +- Milestone ship: merge `phase/05-final-review-ship` → + `milestone/v1.26-pilot-activation` → `main`; tag `v1.25.5` (= the + v1.26 release per prev-minor tagging rule); create Gitea release with + full milestone summary; delete all milestone branches. +- Update `REQUIREMENTS.md` (mark REQ-310..321 complete), `ROADMAP.md` + (mark v1.26 complete), `NORTH_STAR.md` (note Strategic Objectives #1 + + #3 — first real consumer estate; Post-Pilot denominators activated). +- **Requirements:** REQ-310..321 (12 requirements). diff --git a/.ciagent/config.json b/.ciagent/config.json index 5e78a05..118b75e 100644 --- a/.ciagent/config.json +++ b/.ciagent/config.json @@ -4,11 +4,16 @@ "slug": "acdl", "name": "Nova — The New Dawn of DevSecOps", "default": true + }, + { + "slug": "nova-blockchain-exchange", + "name": "Nova Pilot Consumer — Blockchain Stock Exchange", + "default": false } ], "active_project": "acdl", - "active_projects": ["acdl"], - "active_milestone": "v1.25", + "active_projects": ["acdl", "nova-blockchain-exchange"], + "active_milestone": "v1.26", "autonomy": { "level": "full", "escalation_hooks": ["deploy", "delete_data", "merge_to_main"], diff --git a/.ciagent/nova-blockchain-exchange/PROJECT.md b/.ciagent/nova-blockchain-exchange/PROJECT.md new file mode 100644 index 0000000..bec59e0 --- /dev/null +++ b/.ciagent/nova-blockchain-exchange/PROJECT.md @@ -0,0 +1,92 @@ +# Nova Pilot Consumer — Blockchain Stock Exchange + +> **Milestone:** v1.26 — Live Pilot Estate Activation +> **Git:** https://git.cloudinit.dev/continuous-intelligence/nova-blockchain-exchange +> **Local clone:** /root/nova-blockchain-exchange +> **Role:** The first real consumer estate. A stock exchange built on a +> homegrown blockchain, offering equities trading (pilot scope). The +> consumer repo owns the app code + `contract.yaml`; the Nova platform +> (`acdl` repo) provides the deploy workflow, policy engine, and +> attestation gates. + +--- + +## Vision / Core Value + +A self-contained securities-trading exchange where every order, match, +and settlement is recorded as an immutable transaction on a homegrown +Proof-of-Authority (PoA) blockchain. The pilot demonstrates that Nova's +autonomous infrastructure can take a real consumer estate from contract +to production — apply, attest, record — without an operator in the loop +of normal operations. + +## North Star Alignment + +- **Strategic Objective #1** (production-grade zero-touch operations): + this estate is the first real consumer; the pilot activates the + autonomy claim beyond internal demos. +- **Strategic Objective #2** (provable trust): every apply decision + + attestation lands in the Decision Ledger; the settlement-finality + kyverno-json policy (IDEATE) makes trust a policy artifact. +- **Strategic Objective #3** (compounding ROI): unblocks the three + Post-Pilot targets (Touchless Resolution ≥99%, Human Escalation + <0.1%, AI Decision Accuracy ≥99.5%) — the denominators activate when + this estate runs. + +## Domain Boundaries + +- **This repo owns:** the blockchain (consensus, blocks, transactions), + the order-matching engine, the settlement service, the `contract.yaml` + that declares the infrastructure, and the consumer-side deploy workflow + invocation (`uses: acdl/.github/workflows/deploy.yml@v1.25`). +- **The platform (`acdl`) repo owns:** the deploy workflow, the policy + engine (kyverno-json), the contract resolver, the adapter, the + confidence signal, the HITL gates, and the Decision Ledger. + +## Scope: v1.26 Pilot + +- **Equities only** (bonds, derivatives, options deferred to future + milestones — different settlement models). +- **Minimal PoA ledger** — append-only blocks, single validator (pilot), + T+1 settlement finality = block commit. No multi-validator BFT. +- **Homegrown chain** — authored as part of this repo, not deployed on + Ethereum/Solana/Hyperledger. + +## Anti-Goals (v1.26) + +1. Not a general-purpose blockchain platform — purpose-built for + securities settlement in the pilot. +2. Not multi-validator consensus — single validator for the pilot. +3. Not bonds/derivatives/options — equities only this milestone. +4. Not a replacement for the Nova platform — this is a *consumer* of + Nova, not a fork. + +## Key Decisions (v1.26 — established in SPECIFY, refined in CLARIFY) + +| ID | Decision | Rationale | Affects | +|---|---|---|---| +| D-200 | Pilot scope = equities only | Bonds/derivatives/options have very different settlement models; equities (T+1) is the simplest to demonstrate the Nova platform's policy gates over a real estate. | Phase count; requirement scope. | +| D-201 | Homegrown PoA ledger (single validator) | Minimal viable chain for a pilot; settlement finality = block commit. Multi-validator BFT is a future milestone. | Blockchain core design. | +| D-202 | Consumer repo = `nova-blockchain-exchange` (Gitea) | New repo under `continuous-intelligence` org; tracked as 2nd CIAgent project. | Multi-project config. | +| D-203 | AWS account = 581513795199 (existing) | Reuse the bootstrapped account; state bucket + outbox table created in pre-run Workstream A3. | Env JSON binding. | +| D-204 | D-083 (S3 Object Lock/JWS) stays deferred | The SQLite hash-chain + DynamoDB outbox is the pilot's audit record. Tamper-evidence is a future milestone. | Audit ledger scope. | +| D-205 | Cold-only metrics sufficient (D-126) | No hot ops dashboard in the pilot; cold SQLite store + PowerBI export. | Metrics pipeline. | + +## Constraints + +- The consumer repo's deploy MUST go through `deploy.yml@v1.25` (the + reusable workflow) — no direct `terraform apply` bypassing the + platform's policy + attestation gates. +- The `contract.yaml` MUST validate against + `schemas/contract.schema.json`. +- The homegrown blockchain MUST be deterministic (same inputs → same + block) — it is automation, not AI (NORTH_STAR Objective #2 tenet). + +## Context + +- The Nova platform (`acdl` repo) completed v1.25 (kyverno-json Unified + Policy Engine). The swappable `PolicyEngine` adapter is in place. +- The AWS bootstrap (S3 state bucket + DynamoDB outbox) was re-run in + the pre-run (Workstream A3) — the platform components exist. +- The consumer repo was created on Gitea (Workstream A4) and cloned to + `/root/nova-blockchain-exchange`. \ No newline at end of file diff --git a/.ciagent/nova-blockchain-exchange/REQUIREMENTS.md b/.ciagent/nova-blockchain-exchange/REQUIREMENTS.md new file mode 100644 index 0000000..55d1396 --- /dev/null +++ b/.ciagent/nova-blockchain-exchange/REQUIREMENTS.md @@ -0,0 +1,187 @@ +# Requirements — nova-blockchain-exchange (v1.26 pilot) + +> **Project:** nova-blockchain-exchange — blockchain stock exchange (pilot) +> **Milestone:** v1.26 — Live Pilot Estate Activation +> **Scope:** equities only; minimal PoA ledger; T+1 settlement finality. + +--- + +## v1.26 — Live Pilot Estate Activation + +### REQ-310 — Homegrown PoA blockchain core + +The consumer repo implements a minimal Proof-of-Authority blockchain: +append-only blocks, single validator (pilot), SHA-256 block hash chain, +deterministic block production (same ordered transactions → same block). +The chain records every order, match, and settlement as transactions. +Settlement finality = block commit (a transaction is final when its +block is committed to the chain). + +**Must-haves:** +- `chain/block.py` — Block dataclass (index, timestamp, prev_hash, + transactions, nonce, hash). `compute_hash()` deterministic. +- `chain/ledger.py` — Ledger class: `append_block()`, `verify_chain()`, + `get_block(index)`, `get_latest_block()`. Genesis block on init. +- `chain/validator.py` — PoA validator: single validator (config-driven, + pilot), `propose_block(transactions)` → Block, `commit_block(block)`. +- `tests/test_block.py`, `tests/test_ledger.py`, `tests/test_validator.py` + — chain integrity, hash determinism, genesis, append/verify. + +### REQ-311 — Order-matching engine + +A limit-order-book matching engine: buy/sell orders with price + size, +matched at the best price (price-time priority). Produces match +transactions recorded on the chain. + +**Must-haves:** +- `engine/order_book.py` — OrderBook: `add_order(order)`, + `match_orders()` → list of Match (buyer, seller, price, size). +- `engine/order.py` — Order dataclass (id, side, symbol, price, size, + timestamp). +- `tests/test_order_book.py` — match priority, partial fills, no-match. + +### REQ-312 — Settlement service + +T+1 settlement: matches commit to the chain; a settlement is final when +its block is committed. The service reads matches from the order engine, +produces settlement transactions, and submits them to the ledger. + +**Must-haves:** +- `settlement/service.py` — SettlementService: `settle(match)` → + SettlementTransaction, `submit(ledger)`. Idempotent (re-settling a + match is a no-op once final). +- `tests/test_settlement.py` — happy path, idempotency, finality check. + +### REQ-313 — Consumer `contract.yaml` + +The consumer repo declares its infrastructure via a `contract.yaml` at +the repo root, validated against `schemas/contract.schema.json`. The +contract references the Nova platform's deploy workflow +(`uses: acdl/.github/workflows/deploy.yml@v1.25`) and declares the +blockchain exchange stack (the AWS resources the app needs: ECS for +the matching engine, DynamoDB for the ledger, S3 for block storage). + +**Must-haves:** +- `contract.yaml` — id, name (`blockchain-exchange`), environment + (dev/qa/prod variants), infrastructure block. +- `contracts/blockchain-exchange.dev.yml`, `.qa.yml`, `.prod.yml` — + per-environment variants (per-env promotion model, REQ-105). +- `tests/test_contract_validates.py` — schema validation against the + platform's `schemas/contract.schema.json`. + +### REQ-314 — Consumer deploy workflow invocation + +The consumer repo's GitHub/Gitea Actions invoke the Nova platform's +reusable `deploy.yml@v1.25` workflow with `mode: full` for the pilot. +The workflow checks out the consumer repo + the platform repo, runs +`scripts/run_platform.sh`, and records the apply decision + attestation +in the Nova Decision Ledger. + +**Must-haves:** +- `.github/workflows/deploy.yml` — `uses: acdl/.github/workflows/deploy.yml@v1.25` + with `with: { contract: contract.yaml, mode: full, environment: dev }`. +- `.gitea/workflows/deploy.yml` — byte-identical mirror (the platform's + deploy workflow is forge-agnostic). +- `tests/test_deploy_workflow_invocation.py` — asserts the `uses:` ref + + inputs are correct. + +### REQ-315 — Settlement-finality kyverno-json policy (IDEATE I6) + +A kyverno-json policy asserting that every promotion (qa→prod) requires +settlement finality: all matches in the promotion window have committed +blocks. This is the securities-specific extension of v1.25's policy +engine — it applies Nova's compliance posture to the blockchain domain. + +**Must-haves:** +- `policies/settlement-finality.json` — kyverno-json policy over the + settlement-service status JSON (asserts `all_committed: true`). +- `tests/test_settlement_finality_policy.py` — passing + failing + fixtures; skip when `kj` absent. + +### REQ-316 — Pilot-estate regression capability (CAP-025) + +A new capability in the regression gate: "pilot estate apply→attest→record +round-trip." The regression gate asserts that the consumer estate can +run end-to-end (contract resolve → adapter compile → terraform plan → +policy scan → confidence signal → attestation → outbox record) against +the live AWS account `581513795199`. + +**Must-haves:** +- `core/regression_verify.py` gains CAP-025 (live-pilot-apply). +- `tests/test_regression_pilot.py` — the round-trip assertion. + +### REQ-317 — Outcome-backfill emitter (IDEATE I1) + +Wire `apply.completed` / `apply.failed` events back into `fact_decision` +in the cold store so the AI Decision Accuracy metric has a non-`pending` +outcome. Today `fact_decision.outcome` is stuck at `pending` (D-096 +blocker). The backfill emitter reads `run_manifest.completed/failed` +events and updates the corresponding decision's outcome. + +**Must-haves:** +- `core/metrics/outcome_backfill.py` — `backfill(decision_id, outcome)` + updates `fact_decision.outcome` + `fact_decision.backfilled_at`. +- `core/metrics/collector.py` — invokes backfill after run completion. +- `tests/test_outcome_backfill.py`. + +### REQ-318 — `reason='confidence'` escalation tag (IDEATE I2) + +Emit a distinct `reason='confidence'` field on the `block` band's +`ai.decision.made` event so the Human Escalation Frequency metric has a +discriminated numerator. Today `hitl_block` is a boolean from the +manifest; the `reason` discriminator is not stored. + +**Must-haves:** +- `core/confidence_signal.py` — `ai.decision.made` gains + `escalation_reason: 'confidence'` when `band == 'block'`. +- `core/metrics/collector.py` — persists `escalation_reason` into + `fact_run`. +- `tests/test_confidence_escalation_reason.py`. + +### REQ-319 — Env-JSON `state_backend` wiring reconciliation (IDEATE I3) + +The env JSON's `state_backend.bucket` field is currently unused by the +adapter (the adapter computes `nova-tfstate-` directly). +Reconcile: the adapter reads `state_backend.bucket` from the env JSON +(falling back to the computed name for backwards compat). This closes +the wiring gap so the pilot's env JSON is the single source of truth. + +**Must-haves:** +- `adapters/terraform/adapter.py` — reads `env.state_backend.bucket` + when present. +- `tests/test_adapter_state_backend.py`. +- `core/environments/*.json` — `state_backend.bucket` updated to the + real bucket name `nova-tfstate-581513795199-us-east-1`. + +### REQ-320 — Declarative pilot-readiness kyverno-json policy (IDEATE I5) + +A kyverno-json policy asserting the env JSON has a non-placeholder +`account_id` (not `000000000000`) before any `terraform apply`. This is +the declarative gate that prevents a pilot run against a placeholder +account. + +**Must-haves:** +- `adapters/kyverno-json/policies/pilot-readiness/no-placeholder-account.json` +- `tests/test_pilot_readiness_policy.py`. + +### REQ-321 — Docs + adapter README for the consumer estate + +Update `adapters/README.md` (new consumer row), `docs/METRICS.md` (the +3 Post-Pilot metrics now grounded post-pilot), `.ciagent/ARCHITECTURE.md` +(§12.8 — Pilot Estate), and `.ciagent/nova-blockchain-exchange/README.md` +(consumer onboarding guide). + +**Must-haves:** +- `adapters/README.md` — consumer-repo row. +- `docs/METRICS.md` — Post-Pilot metrics grounded note. +- `.ciagent/ARCHITECTURE.md` — §12.8 Pilot Estate. +- `.ciagent/nova-blockchain-exchange/README.md` — onboarding guide. + +### Summary + +12 requirements (REQ-310..321). Equities-only pilot; minimal PoA ledger; +T+1 settlement; consumer deploy via `deploy.yml@v1.25`; 3 Post-Pilot +metrics grounded (outcome backfill + escalation reason + pilot runs); +3 kyverno-json policies extending v1.25 (settlement-finality, +pilot-readiness, + the existing meta-policies apply); env-JSON wiring +reconciled. \ No newline at end of file diff --git a/.ciagent/nova-blockchain-exchange/ROADMAP.md b/.ciagent/nova-blockchain-exchange/ROADMAP.md new file mode 100644 index 0000000..26b47c3 --- /dev/null +++ b/.ciagent/nova-blockchain-exchange/ROADMAP.md @@ -0,0 +1,57 @@ +# Roadmap — nova-blockchain-exchange (v1.26 pilot) + +> **Project:** nova-blockchain-exchange — blockchain stock exchange (pilot) +> **Milestone:** v1.26 — Live Pilot Estate Activation + +--- + +## v1.26 — Live Pilot Estate Activation (active) + +Lift D-096 (live AWS re-provisioning); activate the first real consumer +estate (a stock exchange on a homegrown PoA blockchain, equities only) +against live AWS account `581513795199`; ground the three Post-Pilot +targets in NORTH_STAR.md (Touchless Resolution ≥99%, Human Escalation +<0.1%, AI Decision Accuracy ≥99.5%). The platform repo (`acdl`) provides +the deploy workflow, policy engine, and attestation gates; this repo +provides the app (blockchain + matching engine + settlement) + the +`contract.yaml`. + +Tags run on the **v1.25.x** patch line: `v1.25.0` (P0) → `v1.25.N` +(final phase = milestone release). + +### Phase P1 — blockchain-core (planned, tag v1.25.1) +- REQ-310: Homegrown PoA blockchain core (block, ledger, validator). +- REQ-311: Order-matching engine (limit order book, price-time priority). +- REQ-312: Settlement service (T+1, idempotent, finality = block commit). + +### Phase P2 — consumer-contract-and-deploy (planned, tag v1.25.2) +- REQ-313: Consumer `contract.yaml` + per-env variants. +- REQ-314: Consumer deploy workflow invocation (`deploy.yml@v1.25`). + +### Phase P3 — pilot-metrics-and-policies (planned, tag v1.25.3) +- REQ-315: Settlement-finality kyverno-json policy. +- REQ-316: Pilot-estate regression capability (CAP-025). +- REQ-317: Outcome-backfill emitter. +- REQ-318: `reason='confidence'` escalation tag. +- REQ-319: Env-JSON `state_backend` wiring reconciliation. +- REQ-320: Declarative pilot-readiness kyverno-json policy. + +### Phase P4 — pilot-run-and-docs (planned, tag v1.25.4) +- REQ-321: Docs + adapter README + onboarding guide. +- Live pilot end-to-end run (apply → attest → record) against + `581513795199`. + +### Phase P5 — final review + audit + milestone ship (Final Phase, tag v1.25.5) +- Multi-persona code review across P1..P4. +- Audit: reconstruction test, branch hygiene, commit discipline. +- Milestone ship: merge `phase/05` → `milestone/v1.26-pilot-activation` + → `main`; tag `v1.25.5` (= the v1.26 release per prev-minor tagging + rule); create Gitea release with full milestone summary; delete all + milestone branches. +- Update `REQUIREMENTS.md` (mark REQ-310..321 complete), `ROADMAP.md` + (mark v1.26 complete), `NORTH_STAR.md` (note Strategic Objectives #1 + + #3 — first real consumer estate; Post-Pilot denominators activated). + +After v1.26: future milestones may add bonds/derivatives/options +(different settlement models), multi-validator BFT consensus, and +tamper-evident ledger (D-083 lift). \ No newline at end of file