From 155963d40dfdc73edc052bc1f92dae567e7595ca Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 19 Aug 2026 19:09:05 +0000 Subject: [PATCH] =?UTF-8?q?docs(P00):=20clarify=20=E2=80=94=20v1.27=20ambi?= =?UTF-8?q?guities=20resolved=20(6=20Qs,=20D-220..D-225)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 6 prior-conversation resolutions (D-214..D-219, user-confirmed) + 6 new ambiguities auto-resolved at full autonomy (D-220..D-225): - D-220: NFR milestone (tags on v1.26.x) - D-221: consumer archives in .ciagent/nova-blockchain-exchange/archive/ - D-222: archiving preserves traceability (archive + PROJECT + git) - D-223: IAM_POLICY.md stays active (live baseline, D-207 pending) - D-224: REGRESSION_REPORT regenerates on next run_regression.sh - D-225: PROJECT.md phase-status fix is P2 (correction phase) 0 escalations. Confidence ≥ 0.85 on all new decisions. ---ci--- project: acdl phase: 0 milestone: v1.27 status: clarify ---ci--- --- .ciagent/CHECKPOINT.json | 56 ++------ .ciagent/CLARIFY.md | 295 +++++++++++++++++---------------------- 2 files changed, 137 insertions(+), 214 deletions(-) diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json index b3da06d..ecb5279 100644 --- a/.ciagent/CHECKPOINT.json +++ b/.ciagent/CHECKPOINT.json @@ -1,49 +1,15 @@ { - "phase": 5, - "stage": "complete", - "milestone": "v1.26", - "phase_role": "final", + "phase": 0, + "stage": "specify", + "milestone": "v1.27", + "phase_role": "pre_execution", "attempts": 0, - "updated_at": "2026-08-19T04:00:00Z", + "updated_at": "2026-08-19T04:30:00Z", "project": "acdl", - "projects": [ - "acdl", - "nova-blockchain-exchange" - ], - "active_milestone": "v1.26", - "milestone_branch": "milestone/v1.26-pilot-activation", - "phase_branch": "phase/05-final-review-ship", - "tag_line": "v1.25.x", - "current_phase": { - "phase": 5, - "tag": "v1.25.5", - "status": "complete" - }, - "previous_phase": { - "phase": 4, - "tag": "v1.25.4", - "status": "complete" - }, - "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", - "REQ-322" - ], - "milestone_complete": true, - "milestone_release": { - "tag": "v1.25.5", - "release_id": 791, - "url": "https://git.cloudinit.dev/continuous-intelligence/acdl/releases/tag/v1.25.5" - }, - "notes": "v1.26 COMPLETE. 13 requirements (REQ-310..322). 5 phases. Live apply against 581513795199 succeeded. Confidence 0.800 pass. fact_decision.outcome=succeeded (REQ-317). Hash chain valid. Milestone merged to main. Next run starts a new milestone." + "projects": ["acdl", "nova-blockchain-exchange"], + "active_milestone": "v1.27", + "milestone_branch": "milestone/v1.27-po-state-catalog", + "phase_branch": "phase/00-pre-execution", + "tag_line": "v1.26.x", + "notes": "NFR milestone. PO state catalog + .ciagent/ compression. 3 phases planned (P1 author+archive, P2 fix-stale+wire, P3 final)." } \ No newline at end of file diff --git a/.ciagent/CLARIFY.md b/.ciagent/CLARIFY.md index d1704a0..3609e65 100644 --- a/.ciagent/CLARIFY.md +++ b/.ciagent/CLARIFY.md @@ -1,226 +1,183 @@ -# CLARIFY — v1.26 Live Pilot Estate Activation +# CLARIFY — v1.27 PO State Catalog & Ciagent Compression > **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). +> confidence < 0.60. The prior conversation resolved all material +> ambiguities (4 user-answered questions). This file records the +> assumptions for the v1.27 record. --- ## 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. +The clarify stage identifies ambiguities in the v1.27 specification +and resolves them at full autonomy. The v1.27 spec is the user-approved +plan from the prior conversation + the STATE.md design locked by 4 +question answers. Each ambiguity gets a decision ID (D-214+; continuing +from the v1.26 decisions D-200..D-213), a resolution, a confidence +score, and a rationale. --- -## Ambiguities + Resolutions +## Prior-conversation resolutions (already locked, restated for the record) -### Q1 — Does the consumer repo's `.ciagent/` live in the platform repo or the consumer repo? +These were resolved by user-answered questions in the conversation that +spawned v1.27. They are load-bearing for v1.27 execution and cited +here so the v1.27 record is self-contained. -**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? +### Q-P1 — What should the new PO-reference file catalog? -**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. +**Resolution:** Capability catalog (what the system can do today). +**Confidence:** 1.0 (user-confirmed). **Decision:** D-214. -**Confidence:** 0.95. **Decision:** D-206. +### Q-P2 — How should the new file relate to CAPABILITY_INVENTORY.md? -### Q2 — Is the bootstrap `NOVA_AWS_*` key the root key or the spike-runner key? +**Resolution:** Call it `STATE.md`. PO-owned, ciagent-updated after +milestone implementation. CAPABILITY_INVENTORY.md is archived. +**Confidence:** 1.0 (user-confirmed). **Decision:** D-215. -**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? +### Q-P3 — Where should the file live, and who owns it? -**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). +**Resolution:** Owned by the PO, updated by ciagent after the milestone +is implemented with additives. +**Confidence:** 1.0 (user-confirmed). **Decision:** D-216. -**Confidence:** 0.90. **Decision:** D-207. +### Q-P4 — How should "additive when new features are implemented" be enforced? -### Q3 — Which AWS account does the pilot use: `581513795199` (existing) or a dedicated pilot account? +**Resolution:** On the last phase / milestone ship (the P-final Wave 3 +"milestone ship" step). No regression-gate check in this pass. +**Confidence:** 1.0 (user-confirmed). **Decision:** D-217. -**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)? +### Q-P5 — Should the initial STATE.md backfill all shipped capabilities through v1.26? -**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). +**Resolution:** Backfill all shipped capabilities through v1.26 +(compressed one-liners for v1.1–v1.24; full entries for v1.25 + v1.26). +**Confidence:** 1.0 (user-confirmed). **Decision:** D-218. -**Confidence:** 0.92. **Decision:** D-208. +### Q-P6 — Should the v1.26 pre-execution artifacts (CLARIFY, GRILL, IDEATE, RESEARCH) be archived? -### Q4 — Does "all types of securities" mean all types in v1.26, or equities-only pilot with others deferred? +**Resolution:** Archive all 4 to `.ciagent/archive/` with `-v1.26` +suffixes. The next milestone's P0 writes fresh versions. Decisions are +already folded into PROJECT.md load-bearing decisions + PLAN.md +binding revisions. +**Confidence:** 1.0 (user-confirmed). **Decision:** D-219. -**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. +## Ambiguities + Resolutions (this CLARIFY pass) -**Confidence:** 0.85. **Decision:** D-200 (reaffirmed). +### Q1 — Is v1.27 a feature milestone or an NFR milestone? -### Q5 — Is the homegrown blockchain a real consensus protocol or a minimal PoA ledger? +**Ambiguity:** v1.27 authors `STATE.md` (a new file/capability for the +PO) and archives 11 files. Does the new-file authoring count as `feat:` +(making this a feature milestone, tags on v1.26.x with progressive +patches) or `docs:`/`chore:` (NFR milestone, same tag behavior but +subject to the NFR purity gate)? -**Ambiguity:** "Homegrown blockchain" could mean a full consensus -protocol (multi-validator BFT) or a minimal PoA ledger (single -validator, append-only). +**Resolution:** NFR milestone. `STATE.md` is documentation (a catalog of +existing capabilities), not a new platform capability. The archive moves +are `chore:` (file relocation, lossless). No code, no schema, no +platform behavior change. Tags run on the v1.26.x patch line: +`v1.26.0` (P0) → `v1.26.1..v1.26.3` (P1..P3). The final phase's patch +(`v1.26.3`) IS the milestone release. -**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.95. **Decision:** D-220. -**Confidence:** 0.88. **Decision:** D-201 (reaffirmed). +### Q2 — Where does the consumer-side archive (nova-blockchain-exchange/ROADMAP.md) land? -### Q6 — Does the pilot's `terraform apply` actually run, or is it `--plan-only`? +**Ambiguity:** The platform archive convention is +`.ciagent/archive/-.md`. The consumer subproject +(`nova-blockchain-exchange/`) has no `archive/` subdirectory. Does the +consumer ROADMAP archive at `.ciagent/archive/` (platform-side, mixed) +or `.ciagent/nova-blockchain-exchange/archive/` (consumer-side, new +subdir)? -**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:** Consumer-side. Create +`.ciagent/nova-blockchain-exchange/archive/` and relocate to +`ROADMAP-v1.26.md`. This preserves the per-project path convention +(multi-project mode: `.ciagent//` paths). The platform archive +directory is not mixed with consumer archives. -**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.92. **Decision:** D-221. -**Confidence:** 0.90. **Decision:** D-209. +### Q3 — Does archiving CLARIFY/GRILL/IDEATE/RESEARCH lose the "how v1.26 was specified" traceability? -### Q7 — What AWS resources does the blockchain exchange contract declare? +**Ambiguity:** The pre-execution artifacts document the v1.26 decision +path. Archiving them moves them out of active context. Is the +traceability preserved? -**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:** Yes. Three layers preserve it: (1) the archive files +are byte-identical relocations inside `.ciagent/archive/` (reachable by +agents + git history); (2) the decisions D-200..D-213 are folded into +`PROJECT.md` load-bearing decisions (the durable record); (3) git +history at the v1.26 commits preserves the authoritative state. The +active-context reduction is the point — v1.26 is shipped; the next P0 +writes fresh CLARIFY/GRILL/IDEATE/RESEARCH. -**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.95. **Decision:** D-222. -**Confidence:** 0.82. **Decision:** D-210. +### Q4 — Should IAM_POLICY.md be archived (it predates v1.26 and is dated v1.11)? -### Q8 — Does the outcome-backfill emitter (REQ-317) change the PCR schema? +**Ambiguity:** `IAM_POLICY.md` is dated v1.11 (2026-07-28). It predates +v1.26 by 5 milestones. The D-207 future key-split (P1+ R-3 in +REVIEW-AUDIT-P05) is pending. Archive or keep? -**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:** Keep active. `IAM_POLICY.md` is a live baseline — +referenced by the regression gate +(`tests/test_iam_policy_baseline.py`), enforced by a managed policy on +account `581513795199`, and the D-207 key-split is a pending future- +hardening item. It is not stale; it is a baseline that grows when +grants change. The v1.11 date reflects the last grant addition, not +staleness. -**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.90. **Decision:** D-223. -**Confidence:** 0.95. **Decision:** D-211. +### Q5 — Should REGRESSION_REPORT.{json,md} be refreshed as part of v1.27? -### Q9 — Does the consumer repo need its own test suite + CI, or does the platform's CI cover it? +**Ambiguity:** Both files are dated 2026-08-01 (v1.10 Phase 52), show +CAP-025 absent, and mark live-aws CAPs "Skipped" (state bucket absent +pre-v1.26 re-bootstrap). They are stale. Should v1.27 refresh them? -**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:** No. Both files are machine-managed — written by +`core/regression_verify.py:704-705` on every `run_regression.sh` run. +They regenerate on the next regression run. v1.27 is docs/chore only +(no code); touching machine-managed files by hand creates a drift +source. The stale state is honest (the last gate run was v1.10; the +next run regenerates). The STATE.md Domain 7 row "Regression gate" +notes the current CAP range (CAP-001..025). -**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-224. -**Confidence:** 0.88. **Decision:** D-212. +### Q6 — Does PROJECT.md get the v1.26 phase-status fix in v1.27 P1 or P2? -### Q10 — Is the milestone a feature milestone (tags on v1.25.x) or a major milestone (breaking schema changes)? +**Ambiguity:** The plan splits work into P1 (author + archive) and P2 +(fix stale + wire). The PROJECT.md phase-status fix (P3/P4/P5 pending +→ complete) is a "fix stale" item. P1 or P2? -**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:** P2. P1 is the additive authoring + lossless archive +moves. P2 is the corrections to kept files + the ship-discipline wiring. +This keeps P1 a pure-additive, no-edit phase (easier review + audit) and +P2 the correction phase. The PROJECT.md fix is a correction; P2. -**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. +**Confidence:** 0.85. **Decision:** D-225. --- ## 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. +6 prior-conversation resolutions (D-214..D-219, all user-confirmed) ++ 6 new ambiguities (D-220..D-225, all auto-resolved at full autonomy, +confidence ≥ 0.60). 0 escalations. **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). \ No newline at end of file +- D-220: v1.27 is an NFR milestone (tags on v1.26.x; final patch is the + milestone release). +- D-221: Consumer archives land in `.ciagent/nova-blockchain-exchange/archive/`. +- D-222: Archiving pre-execution artifacts preserves traceability + (archive files + PROJECT.md load-bearing decisions + git history). +- D-223: IAM_POLICY.md stays active (live baseline, test-enforced, + D-207 pending). +- D-224: REGRESSION_REPORT.{json,md} regenerate on next + `run_regression.sh` (machine-managed; v1.27 is docs/chore only). +- D-225: PROJECT.md phase-status fix is P2 (correction phase), not P1 + (additive phase). \ No newline at end of file