acdl/.ciagent/CLARIFY.md

CLARIFY — v1.26 Live Pilot Estate Activation

Autonomy: full. Auto-resolution with assumption logging per config.autonomy.level: "full". No human escalation unless confidence < 0.60 (threshold config.autonomy.decision_confidence_threshold). 10 ambiguities identified; all resolved (confidence ≥ 0.60).

---

Method

The clarify stage identifies ambiguities in the v1.26 specification (PROJECT.md, REQUIREMENTS.md, ROADMAP.md) and resolves them at full autonomy. Each ambiguity gets a decision ID (D-200+; continuing from the v1.26 SPECIFY decisions D-200..D-205), a resolution, a confidence score, and a rationale. Resolutions update PROJECT.md + REQUIREMENTS.md

• ROADMAP.md as needed.

---

Ambiguities + Resolutions

Q1 — Does the consumer repo's .ciagent/ live in the platform repo or the consumer repo?

Ambiguity: The user said "ciagent should track it as a separate project under this same path." Does "this same path" mean the platform repo's .ciagent/ directory (multi-project mode per run.md Step 0), or a separate .ciagent/ inside the consumer repo?

Resolution: The platform repo's .ciagent/ directory. Multi-project mode: .ciagent/config.json projects[] includes both acdl + nova-blockchain-exchange; the consumer's project files (PROJECT.md, REQUIREMENTS.md, ROADMAP.md) live in .ciagent/nova-blockchain-exchange/. The consumer git repo owns the app code + contract.yaml + deploy workflow invocation; the platform repo owns the CIAgent planning artifacts for both projects. This matches run.md Step 0 multi-project mode.

Confidence: 0.95. Decision: D-206.

Q2 — Is the bootstrap NOVA_AWS_* key the root key or the spike-runner key?

Ambiguity: The bootstrap scripts (post-migration) prefer NOVA_BOOTSTRAP_AWS_*, falling back to NOVA_AWS_*. The pre-run (A3) succeeded with NOVA_AWS_*, creating the S3 bucket + DynamoDB table — which requires root or root-equivalent IAM. Is NOVA_AWS_* the root key, or did the bootstrap succeed because the spike-runner policy happens to include S3/DynamoDB create?

Resolution: NOVA_AWS_* has root-equivalent permissions (confirmed empirically: the bootstrap created the S3 bucket + DynamoDB table successfully). For the pilot, NOVA_AWS_* is the bootstrap key. A future hardening milestone should split this into a dedicated NOVA_BOOTSTRAP_AWS_* root key + a least-privilege NOVA_AWS_* runner key (the spike-runner pattern). For v1.26, the single key suffices (pilot scope).

Confidence: 0.90. Decision: D-207.

Q3 — Which AWS account does the pilot use: 581513795199 (existing) or a dedicated pilot account?

Ambiguity: The user said "assume 581513795199." But the env JSONs all show account_id: "000000000000" (placeholder). Does the pilot bind all env JSONs to 581513795199, or only dev (with qa/prod/dr left placeholder until a real multi-account landing zone exists)?

Resolution: Bind dev to 581513795199 for the pilot (D-203, established in SPECIFY). The qa/prod/dr env JSONs remain placeholder 000000000000 this milestone — the pilot runs in dev (autonomous, no HITL gate). Multi-account landing zone (qa/prod/dr on separate accounts) is a future milestone. REQ-319 (env-JSON wiring) updates dev.json's state_backend.bucket to nova-tfstate-581513795199-us-east-1 + account_id to 581513795199; qa/prod/dr get the state_backend.bucket update but keep placeholder account_id (the pilot-readiness policy REQ-320 blocks apply on placeholder accounts — so qa/prod/dr apply is blocked by design until the accounts are bound).

Confidence: 0.92. Decision: D-208.

Q4 — Does "all types of securities" mean all types in v1.26, or equities-only pilot with others deferred?

Ambiguity: The user said "stock market built on homegrown blockchain offering all types of securities." This could mean equities + bonds + derivatives + options all in v1.26, or equities-only pilot with others deferred (the recommended scope from the plan).

Resolution: Equities-only pilot (D-200, established in SPECIFY). Bonds/derivatives/options have very different settlement models (T+1 for equities; T+2 for bonds; derivatives vary; options exercise models). A pilot should demonstrate the Nova platform's policy gates over a real estate — equities (T+1) is the simplest. "All types of securities" is the product vision; v1.26 is the pilot (equities first). The roadmap documents the deferral.

Confidence: 0.85. Decision: D-200 (reaffirmed).

Q5 — Is the homegrown blockchain a real consensus protocol or a minimal PoA ledger?

Ambiguity: "Homegrown blockchain" could mean a full consensus protocol (multi-validator BFT) or a minimal PoA ledger (single validator, append-only).

Resolution: Minimal PoA ledger (D-201, established in SPECIFY). Single validator (config-driven), append-only blocks, SHA-256 hash chain, deterministic block production. Settlement finality = block commit. Multi-validator BFT is a future milestone. The pilot's purpose is to exercise the Nova platform's deploy/policy/attestation gates over a real consumer — the chain needs to be real enough to record transactions, not to solve Byzantine consensus.

Confidence: 0.88. Decision: D-201 (reaffirmed).

Q6 — Does the pilot's terraform apply actually run, or is it --plan-only?

Ambiguity: The platform's run_platform.sh defaults to plan-only (no apply). The deploy.yml workflow's mode input can be full (apply) or plan-only. Does the pilot actually terraform apply (creating real AWS resources for the blockchain exchange), or does it stop at plan?

Resolution: The pilot runs mode: full (apply) for dev only. The apply creates real AWS resources (ECS for the matching engine, DynamoDB for the ledger, S3 for block storage) in account 581513795199. qa/prod/dr are blocked by the pilot-readiness policy (REQ-320) until their accounts are bound (D-208). The apply is autonomous for dev (no HITL gate; confidence threshold 0.50). The ai.decision.made + attestation.recorded events land in the Decision Ledger — but dev attestation is autonomous (no human approver), so only ai.decision.made fires for dev.

Confidence: 0.90. Decision: D-209.

Q7 — What AWS resources does the blockchain exchange contract declare?

Ambiguity: The contract.yaml declares the exchange's infrastructure. What specific AWS resources? The platform's adapter maps contract infrastructure blocks to Terraform. What stack types does the blockchain exchange use?

Resolution: The pilot contract declares 3 infrastructure blocks: (1) ecs (Fargate service for the matching engine + settlement service — the platform's existing microservice module pattern), (2) dynamodb (the ledger table — single-table, PK block_index), (3) s3 (block storage — one object per block, key blocks/{index}.json). The adapter's TYPE_MAP already covers aws_ecs_service, aws_dynamodb_table, aws_s3_bucket (existing L1 primitives). No new adapter stack types needed for the pilot. The contract's infrastructure block references these by module name (microservice for ECS, dynamodb for the table, s3 for the bucket).

Confidence: 0.82. Decision: D-210.

Q8 — Does the outcome-backfill emitter (REQ-317) change the PCR schema?

Ambiguity: REQ-317 wires apply.completed/apply.failed → fact_decision.outcome. Does this touch the PolicyCheckResult schema (PCR) — the v1.25 moat that must not change?

Resolution: No. The outcome backfill touches the metrics cold store (fact_decision table in metrics/nova_metrics.db), not the PCR schema. The PCR schema (schemas/policy_check_result.schema.json) is unchanged. The backfill reads run-manifest events (not PCRs) and updates the decision's outcome column. This respects the v1.25 hard constraint: "DO NOT change schemas/policy_check_result.schema.json."

Confidence: 0.95. Decision: D-211.

Q9 — Does the consumer repo need its own test suite + CI, or does the platform's CI cover it?

Ambiguity: The consumer repo (nova-blockchain-exchange) has app code (blockchain, engine, settlement). Does it run its own tests in its own CI, or does the platform's platform-test.yml cover it?

Resolution: The consumer repo runs its own tests in its own CI (nova-blockchain-exchange/.github/workflows/ci.yml — lint + pytest on the blockchain/engine/settlement code). The platform's platform-test.yml covers the platform repo only (it validates contracts against the schema, runs adapter tests, etc.). The consumer repo's deploy.yml invocation triggers the platform's deploy workflow (which runs run_platform.sh); the platform's policy + attestation gates apply over the consumer's apply. The consumer's unit tests (chain integrity, order matching, settlement) are the consumer's responsibility. REQ-310..312 include consumer-side tests (test_block.py, test_order_book.py, test_settlement.py).

Confidence: 0.88. Decision: D-212.

Q10 — Is the milestone a feature milestone (tags on v1.25.x) or a major milestone (breaking schema changes)?

Ambiguity: v1.26 introduces a 2nd project (multi-project mode) + new requirements. Does this break any schema (→ major milestone, tags on v1.26.x), or is it a feature milestone (tags on v1.25.x)?

Resolution: Feature milestone. No schema breaks: the PCR schema is unchanged (D-211); the contract schema is unchanged (the consumer contract validates against the existing schemas/contract.schema.json); the env JSON gains a real account_id (data, not schema). Multi-project mode is a config change (not a schema break). Tags run on the v1.25.x patch line: v1.25.0 (P0) → v1.25.5 (P5 = milestone release). Per run.md versioning logic: "Feature milestone (at least one feat phase): progressive patches per phase. The final phase's patch IS the milestone release. No separate minor tag."

Confidence: 0.92. Decision: D-213.

---

Summary

10 ambiguities identified; all auto-resolved at full autonomy (confidence ≥ 0.60). 8 new decisions (D-206..D-213) + 3 reaffirmed from SPECIFY (D-200, D-201, D-203). 0 escalations (all ≥ 0.60). The resolutions are recorded in this file + reflected in PROJECT.md / REQUIREMENTS.md / ROADMAP.md updates.

Key decisions:

• D-206: .ciagent/ for both projects in the platform repo (multi-project mode).
• D-207: NOVA_AWS_* has root-equivalent perms; single key for pilot.
• D-208: dev bound to 581513795199; qa/prod/dr stay placeholder (pilot-readiness policy blocks apply on placeholder).
• D-209: Pilot runs mode: full (apply) for dev only; autonomous (no HITL gate).
• D-210: Contract declares ecs + dynamodb + s3 (existing adapter stack types; no new TYPE_MAP entries).
• D-211: Outcome backfill touches metrics cold store, NOT the PCR schema (v1.25 moat preserved).
• D-212: Consumer repo has its own CI + unit tests; platform CI covers platform only.
• D-213: Feature milestone; tags on v1.25.x (no schema breaks).