docs(init): validate specification — v1.26 Live Pilot Estate Activation
---ci--- project: acdl phase: 0 milestone: v1.26 status: specify projects: [acdl, nova-blockchain-exchange] requirements: [REQ-310..REQ-321] ---/ci---
This commit is contained in:
Jon Chery
+17
-29
@@ -1,33 +1,21 @@
|
|||||||
{
|
{
|
||||||
"phase": 5,
|
"phase": 0,
|
||||||
"stage": "complete",
|
"stage": "specify",
|
||||||
"milestone": "v1.25",
|
"milestone": "v1.26",
|
||||||
"phase_role": "final",
|
"phase_role": "pre_execution",
|
||||||
"attempts": 0,
|
"attempts": 0,
|
||||||
"updated_at": "2026-08-12T18:00:00Z",
|
"updated_at": "2026-08-12T21:11:00Z",
|
||||||
"project": "acdl",
|
"project": "acdl",
|
||||||
"milestone_complete": true,
|
"projects": ["acdl", "nova-blockchain-exchange"],
|
||||||
"tag_line": "v1.24.x",
|
"active_milestone": "v1.26",
|
||||||
"tag": "v1.24.5",
|
"milestone_branch": "milestone/v1.26-pilot-activation",
|
||||||
"release": {
|
"phase_branch": "phase/00-specify-clarify-research-plan",
|
||||||
"forge": "gitea",
|
"tag_line": "v1.25.x",
|
||||||
"releases_created": true,
|
"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"],
|
||||||
"release_ids": {
|
"pre_run": {
|
||||||
"v1.24.0": 640,
|
"flaky_test_fixed": "8c68d68 test(metrics): fix attestation-event test freshness time-bomb",
|
||||||
"v1.24.1": 641,
|
"acdl_to_nova_migration": "f844fea chore(bootstrap): migrate ACDL_* env vars to NOVA_*",
|
||||||
"v1.24.2": 642,
|
"aws_bootstrap": "S3 nova-tfstate-581513795199-us-east-1 + DynamoDB nova-outbox created (idempotent, account 581513795199)",
|
||||||
"v1.24.3": 643,
|
"consumer_repo_created": "continuous-intelligence/nova-blockchain-exchange (Gitea, private, init)"
|
||||||
"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."
|
|
||||||
}
|
}
|
||||||
@@ -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),
|
(REQ-297,298,299), plan-JSON policies + pipeline wiring (REQ-300,301,302),
|
||||||
meta-policies (REQ-303), regression-gate policies (REQ-304,305), docs +
|
meta-policies (REQ-303), regression-gate policies (REQ-304,305), docs +
|
||||||
adapter README (REQ-306,307), tests (REQ-308,309).
|
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.
|
||||||
|
|||||||
@@ -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 —
|
(mark v1.25 complete), `NORTH_STAR.md` (note Strategic Objective #2 —
|
||||||
provable trust via a replaceable policy-engine substrate).
|
provable trust via a replaceable policy-engine substrate).
|
||||||
- **Requirements:** REQ-291..309 (19 requirements).
|
- **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).
|
||||||
|
|||||||
@@ -4,11 +4,16 @@
|
|||||||
"slug": "acdl",
|
"slug": "acdl",
|
||||||
"name": "Nova — The New Dawn of DevSecOps",
|
"name": "Nova — The New Dawn of DevSecOps",
|
||||||
"default": true
|
"default": true
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"slug": "nova-blockchain-exchange",
|
||||||
|
"name": "Nova Pilot Consumer — Blockchain Stock Exchange",
|
||||||
|
"default": false
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"active_project": "acdl",
|
"active_project": "acdl",
|
||||||
"active_projects": ["acdl"],
|
"active_projects": ["acdl", "nova-blockchain-exchange"],
|
||||||
"active_milestone": "v1.25",
|
"active_milestone": "v1.26",
|
||||||
"autonomy": {
|
"autonomy": {
|
||||||
"level": "full",
|
"level": "full",
|
||||||
"escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
|
"escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
|
||||||
|
|||||||
@@ -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`.
|
||||||
@@ -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-<AWS_ACCOUNT_ID>` 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.
|
||||||
@@ -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).
|
||||||
Reference in New Issue
Block a user