docs(P00): research findings — v1.26 (PoA blockchain, deploy model, DynamoDB gap, personas)
---ci--- project: acdl phase: 0 milestone: v1.26 status: research requirements: [REQ-310..REQ-322] personas: [lead-developer, backend-engineer, data-engineer, policy-engineer, blockchain-engineer] ---/ci---
This commit is contained in:
Jon Chery
+151
-114
@@ -1,132 +1,169 @@
|
||||
---
|
||||
project: acdl
|
||||
milestone: v1.25
|
||||
milestone: v1.26
|
||||
generated_at: 2026-08-12
|
||||
generator: lead-developer
|
||||
verification_toolchain:
|
||||
typecheck: "python3 -m py_compile core/policy_engine.py adapters/kyverno-json/kyverno_json_engine.py tests/test_policy_engine.py tests/test_kyverno_json_engine.py"
|
||||
test: "pytest tests/test_policy_engine.py tests/test_kyverno_json_engine.py tests/test_adapter.py tests/test_contract_resolver.py tests/test_confidence_signal.py tests/test_checkov_adapter.py tests/test_kyverno_adapter.py tests/test_pipeline.py -v"
|
||||
lint: "ruff check core/policy_engine.py adapters/kyverno-json/ 2>/dev/null || python3 -m py_compile core/policy_engine.py"
|
||||
typecheck: "python3 -m py_compile core/confidence_signal.py core/metrics/outcome_backfill.py adapters/terraform/adapter.py modules/l1/dynamodb/terraform/main.tf"
|
||||
test: "pytest tests/test_adapter.py tests/test_contract_resolver.py tests/test_confidence_signal.py tests/test_outcome_backfill.py tests/test_settlement_finality_policy.py tests/test_pilot_readiness_policy.py tests/test_block.py tests/test_order_book.py tests/test_settlement.py -v"
|
||||
lint: "ruff check core/metrics/outcome_backfill.py adapters/kyverno-json/policies/pilot-readiness/ adapters/kyverno-json/policies/settlement-finality/ 2>/dev/null || python3 -m py_compile core/metrics/outcome_backfill.py"
|
||||
note: |
|
||||
v1.25 is the kyverno-json Unified Policy Engine milestone — a feat
|
||||
v1.26 is the Live Pilot Estate Activation milestone — a feat
|
||||
milestone. Four active personas: lead-developer (coordination +
|
||||
docs + ARCHITECTURE.md §12.7), backend-engineer (core/policy_engine.py
|
||||
protocol + registry + contract_resolver.py wiring + run_platform.sh
|
||||
Step 5 + pipeline tests), policy-engineer (adapters/kyverno-json/
|
||||
engine + policies across all 4 target dirs + meta-policies + policy
|
||||
tests + adapter README + STANDARDS.md policy-authoring section),
|
||||
data-engineer (config.json policy object + schemas/README.md note +
|
||||
capability-inventory JSON fixture for regression policies).
|
||||
frontend-engineer stays deactivated (no UI). The policy-engineer is a
|
||||
new custom persona created for this milestone's policy domain (see
|
||||
RESEARCH.md §4 — kyverno-json + JMESPath is a distinct framework from
|
||||
backend-engineer's fastify/hono).
|
||||
docs + ARCHITECTURE.md §12.8), backend-engineer (confidence_signal.py
|
||||
escalation reason + outcome_backfill.py + run_platform.sh wiring +
|
||||
env-JSON state_backend reconciliation), data-engineer (DynamoDB L1
|
||||
primitive + metrics cold store outcome backfill), policy-engineer
|
||||
(kyverno-json pilot-readiness + settlement-finality policies), +
|
||||
blockchain-engineer (custom, phase-specific — chain core + order
|
||||
engine + settlement). frontend-engineer is deactivated (no UI).
|
||||
Territory enforcement: warn (the pilot is cross-territory by
|
||||
nature — the consumer repo + the platform repo share the milestone).
|
||||
---
|
||||
|
||||
# ACDL — Persona Roster (v1.25 kyverno-json Unified Policy Engine)
|
||||
# PERSONAS — v1.26 Live Pilot Estate Activation
|
||||
|
||||
> v1.25 roster. Four active personas + one deactivated. This is a feat
|
||||
> milestone: the work is a swappable policy-engine protocol + a new
|
||||
> adapter + policies across 4 Nova artifacts + pipeline wiring + docs.
|
||||
> The policy-engineer is a new custom persona — kyverno-json + JMESPath
|
||||
> is a specialized domain that doesn't fit backend-engineer's
|
||||
> fastify/hono frameworks or data-engineer's drizzle/postgresql.
|
||||
> Generated by the lead-developer at the end of RESEARCH. Assesses the
|
||||
> project domains, activates/deactivates personas, creates custom
|
||||
> personas for domains beyond the default four, aligns frameworks +
|
||||
> territory + constraints to the actual project structure.
|
||||
|
||||
## Active personas
|
||||
## Active Roster (5)
|
||||
|
||||
### lead-developer
|
||||
- **Domain:** coordination + docs
|
||||
- **Frameworks:** []
|
||||
- **Constraints:** ["pragmatic", "battle-tested defaults", "docs match code", "swap boundary is the moat"]
|
||||
- **Territory:**
|
||||
- `.ciagent/ARCHITECTURE.md` (§12.7 Policy Engine Registry — NEW)
|
||||
- `.ciagent/PROJECT.md` (v1.25 section)
|
||||
- `.ciagent/REQUIREMENTS.md` (v1.25 section)
|
||||
- `.ciagent/ROADMAP.md` (v1.25 section)
|
||||
- `.ciagent/PLAN.md`, `.ciagent/RESEARCH.md`, `.ciagent/CLARIFY.md`,
|
||||
`.ciagent/GRILL.md`, `.ciagent/PERSONAS.md`
|
||||
- `docs/METRICS.md` (swappable engine narrative — REQ-307)
|
||||
- **Reason:** Owns the milestone coordination + the architecture
|
||||
narrative. The swap boundary (PolicyEngine protocol) is the moat per
|
||||
Strategic Objective #2 — the lead-developer owns the boundary
|
||||
description in ARCHITECTURE.md §12.7 and the docs/METRICS.md note.
|
||||
No Python policy code (backend-engineer + policy-engineer territory).
|
||||
No UI (frontend-engineer deactivated).
|
||||
### 1. lead-developer (active)
|
||||
- **active:** true
|
||||
- **phase_specific:** false
|
||||
- **reason:** Coordinates task decomposition + resolves conflicts between
|
||||
engineering personas. Owns the milestone narrative (PROJECT.md,
|
||||
ROADMAP.md, ARCHITECTURE.md §12.8). Final architectural decisions when
|
||||
personas disagree (e.g. where the outcome-backfill emitter lives).
|
||||
- **domain:** project coordination, milestone narrative, cross-persona
|
||||
conflict resolution.
|
||||
- **frameworks:** none (coordination role).
|
||||
- **territory:** `.ciagent/`, `docs/METRICS.md`, `adapters/README.md`,
|
||||
`modules/README.md`, `modules/STANDARDS.md`.
|
||||
- **constraints:** does not write Python/Terraform (delegates to
|
||||
backend/data-engineer); does not author policies (delegates to
|
||||
policy-engineer); does not author chain code (delegates to
|
||||
blockchain-engineer).
|
||||
|
||||
### backend-engineer
|
||||
- **Domain:** backend (Python + bash + pipeline wiring)
|
||||
- **Frameworks:** ["boto3", "terraform"]
|
||||
- **Constraints:** ["api-first", "strict-typing", "engine-agnostic confidence signal", "fail-soft when kj absent"]
|
||||
- **Territory:**
|
||||
- `core/policy_engine.py` (NEW — PolicyEngine Protocol + PolicyEngineRegistry + NullEngine)
|
||||
- `core/contract_resolver.py` (MODIFIED — invoke registry pre/post resolve)
|
||||
- `scripts/run_platform.sh` (MODIFIED — Step 5 kyverno-json parallel pass)
|
||||
- `scripts/install-kyverno-json.sh` (NEW)
|
||||
- `tests/test_policy_engine.py` (NEW — protocol conformance, registry, NullEngine)
|
||||
- `tests/test_run_platform_plan_json_policies.py` (NEW — script-substring assertion)
|
||||
- `.github/workflows/ci.yml` + `.gitea/workflows/ci.yml` (MODIFIED — Go + kj install)
|
||||
- **Reason:** Owns the Python protocol layer + the pipeline wiring. The
|
||||
`PolicyEngine` Protocol + `PolicyEngineRegistry` are Python structural-
|
||||
typing constructs (PEP 544) — backend-engineer's strict-typing
|
||||
constraint. The `contract_resolver.py` wiring + `run_platform.sh`
|
||||
Step 5 are backend territory. Does NOT write kyverno-json policy
|
||||
files (policy-engineer territory) — only the Python that *invokes* the
|
||||
engine. Does NOT modify the confidence signal (it already consumes
|
||||
`list[PolicyCheckResult]` engine-agnostically — PROJECT.md hard-
|
||||
constraint).
|
||||
### 2. backend-engineer (active)
|
||||
- **active:** true
|
||||
- **phase_specific:** false
|
||||
- **reason:** Owns the platform-side Python changes: confidence signal
|
||||
escalation reason (REQ-318), outcome-backfill emitter (REQ-317),
|
||||
env-JSON state_backend wiring (REQ-319), adapter test updates for
|
||||
DynamoDB (REQ-322), regression CAP-025 (REQ-316).
|
||||
- **domain:** core Python (confidence_signal.py, metrics/, adapter.py,
|
||||
regression_verify.py, contract_resolver.py), run_platform.sh wiring.
|
||||
- **frameworks:** Python 3.12, pytest, boto3, SQLite, DynamoDB.
|
||||
- **territory:** `core/confidence_signal.py`, `core/metrics/`,
|
||||
`adapters/terraform/adapter.py`, `core/regression_verify.py`,
|
||||
`core/environments/`, `scripts/run_platform.sh`, `tests/test_adapter.py`,
|
||||
`tests/test_confidence_signal.py`, `tests/test_outcome_backfill.py`,
|
||||
`tests/test_regression_pilot.py`.
|
||||
- **constraints:** does not change `schemas/policy_check_result.schema.json`
|
||||
(v1.25 moat, D-211); does not change `schemas/contract.schema.json`
|
||||
(no schema breaks, D-213); does not author Terraform modules
|
||||
(delegates to data-engineer for DynamoDB); does not author policies
|
||||
(delegates to policy-engineer); does not author chain code (delegates
|
||||
to blockchain-engineer).
|
||||
|
||||
### policy-engineer
|
||||
- **Domain:** policy (declarative compliance rules)
|
||||
- **Frameworks:** ["kyverno-json", "jmespath", "kyverno ValidatingPolicy"]
|
||||
- **Constraints:** ["declarative-policies", "no-imperative-rules", "schema-validated", "severity-via-annotation", "assertion-trees-not-foreach"]
|
||||
- **Territory:**
|
||||
- `adapters/kyverno-json/` (NEW — engine impl + __init__.py + README)
|
||||
- `adapters/kyverno-json/kyverno_json_engine.py` (NEW — KyvernoJsonEngine)
|
||||
- `adapters/kyverno-json/policies/` (NEW — all 4 target dirs: contract/, stack-ir/, plan-json/, meta/, regression/)
|
||||
- `adapters/kyverno-json/policies/_smoke.json` (NEW)
|
||||
- `adapters/README.md` (MODIFIED — new adapter row + PolicyEngine Protocol section)
|
||||
- `tests/test_kyverno_json_engine.py` (NEW — PCR schema validity, defensive parsing)
|
||||
- `tests/test_stack_ir_policies.py` (NEW)
|
||||
- `tests/test_plan_json_policies.py` (NEW)
|
||||
- `tests/test_meta_policies.py` (NEW)
|
||||
- `tests/test_regression_policies.py` (NEW)
|
||||
- `tests/fixtures/stack_ir/`, `tests/fixtures/plan_json/`, `tests/fixtures/capability_inventory.json` (NEW)
|
||||
- `modules/STANDARDS.md` (MODIFIED — Policy authoring standard section — REQ-307)
|
||||
- **Reason:** The policy-engineer owns the declarative policy artifacts.
|
||||
kyverno-json's `ValidatingPolicy` + assertion trees + JMESPath is a
|
||||
distinct framework from backend-engineer's fastify/hono and requires
|
||||
its own constraints: no imperative rules (everything is an assertion
|
||||
tree), severity via the `nova.cloudinit.dev/severity` annotation (not
|
||||
in the engine adapter), no `forEach` (use the `~` modifier). The
|
||||
adapter pattern (engine ↔ protocol ↔ registry) is backend-engineer
|
||||
territory, but the policy *content* and the engine *translation*
|
||||
(`_to_pcr()`) are policy-engineer territory because they require
|
||||
kyverno-json output-shape knowledge. Created per RESEARCH.md §4 — this
|
||||
is a phase-spanning persona (active for P1..P4), not phase-specific.
|
||||
### 3. data-engineer (active)
|
||||
- **active:** true
|
||||
- **phase_specific:** false
|
||||
- **reason:** Owns the DynamoDB L1 primitive (REQ-322) — the single
|
||||
platform-side module build-out. Owns the metrics cold store
|
||||
outcome-backfill integration (REQ-317, the `fact_decision.outcome`
|
||||
column + `backfilled_at` timestamp). Owns the env-JSON data updates
|
||||
(REQ-319, `core/environments/*.json` account_id + state_backend.bucket).
|
||||
- **domain:** Terraform modules (`modules/l1/`), schema definitions
|
||||
(`interface.json`), registry (`modules/registry.json`), metrics cold
|
||||
store (`metrics/nova_metrics.db`, `core/metrics/collector.py`).
|
||||
- **frameworks:** Terraform, JSON, SQLite, DynamoDB, boto3.
|
||||
- **territory:** `modules/l1/dynamodb/`, `modules/registry.json`,
|
||||
`modules/README.md`, `core/environments/*.json`,
|
||||
`core/metrics/collector.py`, `tests/test_adapter.py` (DynamoDB
|
||||
emission test).
|
||||
- **constraints:** does not change the adapter (stateless, v1.11);
|
||||
follows the v1.8 NFR defaults (encryption + deletion protection +
|
||||
PITR); follows the module standards (`modules/STANDARDS.md`).
|
||||
|
||||
### data-engineer
|
||||
- **Domain:** data (config schema + structured fixtures)
|
||||
- **Frameworks:** ["jsonschema", "yaml"]
|
||||
- **Constraints:** ["schema-first", "type-safe config", "backward-compatible additions"]
|
||||
- **Territory:**
|
||||
- `.ciagent/config.json` (MODIFIED — new `policy` object: engine + policy_root)
|
||||
- `schemas/policy_check_result.schema.json` (READ-ONLY — no change per D-116)
|
||||
- `schemas/README.md` (MODIFIED — note engine: "kyverno" shared by K8s adapter + kj)
|
||||
- `tests/fixtures/capability_inventory.json` (NEW — clean + drifted inventory fixtures for regression policies)
|
||||
- **Reason:** The `config.json.policy` object is a schema-first addition
|
||||
(new top-level key with `engine` + `policy_root` fields). The
|
||||
capability-inventory JSON fixtures for the regression-gate policies
|
||||
(REQ-304) are structured data — the data-engineer owns the fixture
|
||||
shape. The `policy_check_result.schema.json` is read-only (D-116 — no
|
||||
enum change); the data-engineer documents the `engine: "kyverno"`
|
||||
sharing in `schemas/README.md`. No migrations (no database). No Python
|
||||
(backend-engineer + policy-engineer territory).
|
||||
### 4. policy-engineer (active, custom — added in v1.25)
|
||||
- **active:** true
|
||||
- **phase_specific:** false
|
||||
- **reason:** Owns the kyverno-json policy authoring for the pilot:
|
||||
settlement-finality (REQ-315), pilot-readiness (REQ-320). Extends
|
||||
v1.25's policy engine to the securities domain.
|
||||
- **domain:** declarative policies (kyverno-json ValidatingPolicy YAML),
|
||||
JMESPath assertions, policy tests.
|
||||
- **frameworks:** kyverno-json, JMESPath, JSON, pytest.
|
||||
- **territory:** `adapters/kyverno-json/policies/pilot-readiness/`,
|
||||
`adapters/kyverno-json/policies/settlement-finality/`,
|
||||
`tests/test_settlement_finality_policy.py`,
|
||||
`tests/test_pilot_readiness_policy.py`.
|
||||
- **constraints:** policies are declarative (no imperative Python);
|
||||
`is_configured()` guard skips gracefully when `kj` absent; follows
|
||||
the v1.25 policy-authoring standard (`modules/STANDARDS.md` policy
|
||||
section + `adapters/kyverno-json/README.md`).
|
||||
|
||||
## Deactivated personas
|
||||
### 5. blockchain-engineer (active, custom, phase-specific — added in v1.26)
|
||||
- **active:** true
|
||||
- **phase_specific:** true (created for v1.26 P1; removed after P1
|
||||
unless the chain has ongoing work in P2..P4)
|
||||
- **reason:** The pilot introduces a homegrown blockchain — a domain
|
||||
beyond the default four personas. Owns the chain core (block, ledger,
|
||||
validator, REQ-310), the order-matching engine (REQ-311), the
|
||||
settlement service (REQ-312), and the consumer `contract.yaml`
|
||||
(REQ-313) + deploy invocation (REQ-314).
|
||||
- **domain:** blockchain consensus (PoA, single validator), order
|
||||
matching (limit order book, price-time priority), settlement
|
||||
(T+1, finality = block commit), consumer-repo deploy model.
|
||||
- **frameworks:** Python 3.12 (the chain is Python, not Solidity/Go —
|
||||
it's a homegrown ledger, not a smart-contract platform), pytest,
|
||||
YAML (contract.yaml), GitHub Actions / Gitea Actions (deploy.yml
|
||||
invocation).
|
||||
- **territory:** `/root/nova-blockchain-exchange/` (the consumer repo:
|
||||
`chain/`, `engine/`, `settlement/`, `contract.yaml`,
|
||||
`contracts/*.yml`, `.github/workflows/deploy.yml`,
|
||||
`.gitea/workflows/deploy.yml`, `tests/`).
|
||||
- **constraints:** the chain is deterministic (same inputs → same block)
|
||||
— it is automation, not AI (NORTH_STAR Objective #2 tenet); equities
|
||||
only (D-200); single validator PoA (D-201); the consumer deploy MUST
|
||||
go through `deploy.yml@v1.25` (no direct terraform apply); the
|
||||
contract MUST validate against `schemas/contract.schema.json`.
|
||||
|
||||
### frontend-engineer
|
||||
## Deactivated (1)
|
||||
|
||||
### frontend-engineer (inactive)
|
||||
- **active:** false
|
||||
- **Reason:** ACDL has no frontend (no package.json — confirmed in
|
||||
config.json personas.personas[frontend-engineer].reason). v1.25 adds
|
||||
no UI work — the policy engine is backend + policy artifacts only.
|
||||
Deactivated per the v1.15+ convention.
|
||||
- **phase_specific:** false
|
||||
- **reason:** The pilot has no UI — the blockchain exchange is a
|
||||
backend service (matching engine + settlement). The consumer repo
|
||||
has no web/frontend. Reactivated if a future milestone adds a trading
|
||||
dashboard.
|
||||
|
||||
## Phase-Specific Notes
|
||||
|
||||
- **blockchain-engineer** is created for v1.26 P1 (blockchain core +
|
||||
order engine + settlement). If P2..P4 have no chain changes, the
|
||||
persona is removed after P1 (the chain is a stable substrate for the
|
||||
pilot run). If P2 (consumer-contract-and-deploy) requires chain
|
||||
adjustments, the persona stays through P2.
|
||||
- **policy-engineer** is active for P3 (pilot-metrics-and-policies) +
|
||||
may consult on P4 (pilot run policy verification).
|
||||
- **data-engineer** is active for P3 (DynamoDB primitive + outcome
|
||||
backfill + env-JSON) + P4 (regression CAP-025 may touch the registry).
|
||||
|
||||
## Territory Enforcement
|
||||
|
||||
- **Mode:** `warn` (the pilot is cross-territory by nature — the
|
||||
consumer repo + the platform repo share the milestone; the
|
||||
blockchain-engineer works in the consumer repo, backend/data/policy
|
||||
engineers work in the platform repo).
|
||||
- **Cross-territory collisions:** REQ-322 (DynamoDB primitive) is
|
||||
data-engineer territory, but the adapter test update
|
||||
(`tests/test_adapter.py` `EXPECTED_L1_KEYS`) is backend-engineer
|
||||
territory. The lead-developer resolves: data-engineer authors the
|
||||
module + registry; backend-engineer updates the test assertion
|
||||
(the test is backend territory, the module is data territory).
|
||||
Reference in New Issue
Block a user