docs(P00): clarify — D-241/D-242/D-243 + STATE.md intake override
---ci--- project: acdl phase: 0 milestone: v1.30 status: clarify decisions: [D-241, D-242, D-243] ---/ci---
This commit is contained in:
CIAgent
@@ -1,10 +1,10 @@
|
||||
{
|
||||
"phase": 0,
|
||||
"stage": "specify",
|
||||
"stage": "clarify",
|
||||
"milestone": "v1.30",
|
||||
"phase_role": "pre_execution",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-20T13:15:00Z",
|
||||
"updated_at": "2026-08-20T13:25:00Z",
|
||||
"project": "acdl",
|
||||
"projects": ["acdl", "nova-blockchain-exchange"],
|
||||
"active_milestone": "v1.30",
|
||||
@@ -23,5 +23,5 @@
|
||||
"branches_deleted": true,
|
||||
"releases_created": true
|
||||
},
|
||||
"notes": "v1.30 Phase 0 SPECIFY complete. REQ-372.1...12 added to REQUIREMENTS.md. v1.30 milestone section + Slide Content Map appended to PROJECT.md. Tags run on v1.29.x line: v1.29.1 (P0), v1.29.2 (P1), v1.29.3 (P2 = milestone release). Next: CLARIFY (D-241..D-243)."
|
||||
"notes": "v1.30 Phase 0 CLARIFY complete. D-241 (discrete artifact, overrides STATE.md intake assumption 3), D-242 (narrow render_pptx.py extension), D-243 (month-only date anchor). STATE.md intake assumption 3 overridden. Spec §7 Q1-Q4 auto-resolved at full autonomy. Next: RESEARCH."
|
||||
}
|
||||
+162
-449
@@ -1,500 +1,213 @@
|
||||
# CLARIFY — v1.28 CLI Canonicalization + Identity Layer
|
||||
# CLARIFY — v1.30 Single-shot Leadership Deck
|
||||
|
||||
> **Autonomy:** full. Auto-resolution with assumption logging per
|
||||
> `config.autonomy.level: "full"`. No human escalation unless confidence
|
||||
> < 0.60. The user-approved re-mapping plan (v1.18 spec → v1.28) resolved
|
||||
> the headline discrepancy. This file records the remaining ambiguities
|
||||
> and the grounding gaps surfaced in pre-flight.
|
||||
> `config.autonomy.level: "full"`. No human escalation unless
|
||||
> confidence < 0.60. The user confirmed the 4 framing decisions
|
||||
> (milestone numbering, render pipeline path, stale intake
|
||||
> assumption override, smoke test PPTX gate) in the pre-run planning
|
||||
> conversation. This file records the formal D-IDs and the spec §7
|
||||
> open-question resolutions.
|
||||
|
||||
---
|
||||
|
||||
## Method
|
||||
|
||||
The clarify stage identifies ambiguities in the v1.28 specification and
|
||||
resolves them at full autonomy. The v1.28 spec is the user-provided
|
||||
"Universal Feature Specification — v1.18 CLI Canonicalization + Identity
|
||||
Layer," re-mapped to v1.28 (milestone number, tag line, and all
|
||||
ID namespaces) per the user-approved plan. Each ambiguity gets a
|
||||
decision ID (D-226+, continuing from v1.27's D-214..D-225), a resolution,
|
||||
a confidence score, and a rationale.
|
||||
The clarify stage identifies ambiguities in the v1.30 specification
|
||||
(REQ-372 v1.0, locked 2026-08-20) and resolves them at full autonomy.
|
||||
The spec is the user-provided "REQ-372 — Nova Leadership Presentation
|
||||
Deck." Each ambiguity gets a decision ID (D-241+, continuing from
|
||||
v1.29's D-232..D-240), a resolution, a confidence score, and a
|
||||
rationale.
|
||||
|
||||
---
|
||||
|
||||
## Prior-conversation resolutions (already locked, restated for the record)
|
||||
|
||||
These were resolved by the user-approved re-mapping plan in the
|
||||
conversation that spawned v1.28. They are load-bearing for v1.28
|
||||
execution.
|
||||
These were resolved by the user in the pre-run planning conversation
|
||||
that spawned v1.30. They are load-bearing for v1.30 execution.
|
||||
|
||||
### Q-P1 — The source spec is titled "v1.18" but v1.18 already shipped. What milestone is this?
|
||||
### Q-M1 — The cover note/spec say "v1.29.x" but the checkpoint says v1.29 is complete and active_milestone is v1.30. What is the milestone number?
|
||||
|
||||
**Resolution:** Re-map the spec's *content* (CLI Canonicalization +
|
||||
Identity Layer) to **v1.28**, the next milestone after v1.27 (complete).
|
||||
Tags run on the **v1.27.x** line (P0 = `v1.27.0`). Milestone branch:
|
||||
`milestone/v1.28-cli-identity`.
|
||||
**Confidence:** 1.0 (user-confirmed — "Re-map to v1.28"). **Decision:** n/a (milestone identity, not a D-ID).
|
||||
**Resolution:** The milestone is **v1.30**. The cover note's "v1.29.x"
|
||||
is the **tag line** (per run.md branch strategy, tags run on the
|
||||
previous minor's patch line: milestone v1.30 → tags v1.29.1,
|
||||
v1.29.2, v1.29.3). The milestone branch is
|
||||
`milestone/v1.30-leadership-deck`. v1.29 is complete (merged to main
|
||||
`9dc5669`, tag `v1.28.6`).
|
||||
**Confidence:** 1.0 (user-confirmed — "Milestone v1.30, tags v1.29.x").
|
||||
**Decision:** n/a (milestone identity, not a D-ID).
|
||||
|
||||
### Q-P2 — The spec's "locked inputs" (D-NEW-26, kj engine, Nova-idp, INV-63/64/65, CAP-025..030, REQ-001..031) don't exist in the repo. How to handle?
|
||||
### Q-M2 — The cover note says `scripts/render_pptx.py docs/presentations/nova-leadership-deck.md` but render_pptx.py expects `{deck}-marp.md` naming. How to resolve?
|
||||
|
||||
**Resolution:** Author them fresh in this milestone's CLARIFY/RESEARCH as
|
||||
**D-226..D-231, INV-12..17, CAP-033..038, REQ-323..353**. The `kj` engine
|
||||
is mapped to the existing **kyverno-json** engine (INV-4 swappable) — no
|
||||
new engine is built. CAP/INV/REQ IDs are re-allocated to avoid collisions
|
||||
with shipped history (CAP-025..032 and INV-1..11 are blockchain/pilot).
|
||||
**Confidence:** 1.0 (user-confirmed — "Re-map to v1.28"). **Decision:** D-227 (kj→kyverno-json), plus the ID-allocation block in REQUIREMENTS.md.
|
||||
**Resolution:** Author the source as
|
||||
`docs/presentations/nova-leadership-deck-marp.md` to fit the existing
|
||||
`-marp.md` pipeline convention. Narrowly extend `render_pptx.py` to
|
||||
accept an explicit source `.md` path + `--output` filename, and to
|
||||
render a right-aligned footer textbox on every slide (python-pptx
|
||||
does not read the Marp `footer:` directive). The output is
|
||||
`nova-leadership-deck.pptx` per spec REQ-372.2. Formalized as D-242.
|
||||
**Confidence:** 1.0 (user-confirmed — "Author source as
|
||||
nova-leadership-deck-marp.md, extend render_pptx.py").
|
||||
**Decision:** D-242.
|
||||
|
||||
### Q-P3 — The spec claims a "Cognito drop." No Cognito exists in the repo. What does NFR-5 mean?
|
||||
### Q-M3 — The post-v1.29 STATE.md intake (assumption 3) says the leadership deck "is a compression, not a rewrite" of the 23-slide citizen-developer deck. The cover note + spec explicitly forbid compression. How to handle?
|
||||
|
||||
**Resolution:** NFR-5 (no AWS-managed identity in the path) is a
|
||||
**greenfield constraint**, not a migration. Nova-idp is built fresh; no
|
||||
Cognito/IAM Identity Center is *introduced*. The "drop" framing is
|
||||
aspirational language from the source spec, not a literal removal.
|
||||
**Confidence:** 1.0. **Decision:** D-226 (recorded below; NFR-5 restated
|
||||
as a greenfield constraint in INV-15).
|
||||
**Resolution:** Override the stale intake assumption. The leadership
|
||||
deck is a **discrete, hand-authored artifact** — NOT a compression.
|
||||
The existing citizen-developer deck
|
||||
(`nova-autonomous-cloud-delivery-marp.md`) remains untouched. The
|
||||
spec §2.2 + cover note forbid compression/mirroring; the Slide
|
||||
Content Map is hand-authored content, not derived. Update STATE.md
|
||||
intake assumption 3 to reflect the discrete-artifact decision.
|
||||
Formalized as D-241.
|
||||
**Confidence:** 1.0 (user-confirmed — "Override with spec's
|
||||
discrete-artifact decision").
|
||||
**Decision:** D-241.
|
||||
|
||||
### Q-M4 — The smoke test (REQ-372.8f) must assert PPTX file existence. Given the render environment limitations, should the PPTX-existence check be a hard fail or a conditional skip?
|
||||
|
||||
**Resolution:** **Hard fail** if `.pptx` absent. The deck must be
|
||||
rendered before ship. The render environment is resolved (python-pptx
|
||||
installed via user-site `pip install --user --break-system-packages`;
|
||||
no Chromium needed since python-pptx is the render path, not Marp
|
||||
CLI). If the environment cannot render, that is a ship blocker to
|
||||
resolve — not a reason to weaken the gate.
|
||||
**Confidence:** 1.0 (user-confirmed — "Hard fail if .pptx absent").
|
||||
**Decision:** n/a (gate severity, not a D-ID — recorded in PLAN.md).
|
||||
|
||||
---
|
||||
|
||||
## Open questions from the spec's §7 (auto-resolved at full autonomy)
|
||||
|
||||
### Q1 — Argon2 native dependency in Lambda runtime
|
||||
### Q1 — Specific meeting date inside August 2026
|
||||
|
||||
`argon2-cffi` has a C extension that may not build cleanly in the Lambda
|
||||
Python 3.12 runtime.
|
||||
**Spec context:** The presentation is in August 2026, but no specific
|
||||
day is named. Slide 7 references "Infrastructure & Operations
|
||||
leadership" without naming a day.
|
||||
|
||||
**Resolution (D-228):** Use `argon2-cffi` with bundled wheels; if the
|
||||
extension fails to load, fall back to the pure-Python implementation. If
|
||||
both fail, document the Fargate migration path for the auth Lambda.
|
||||
CAP-036 covers end-to-end verification.
|
||||
**Confidence:** 0.85. **Rationale:** Bundled wheels are the standard
|
||||
workaround for Lambda native deps; the pure-Python fallback is a safe
|
||||
degradation. Fargate is the escape hatch if Lambda's runtime is
|
||||
fundamentally incompatible. RESEARCH will validate wheel availability for
|
||||
Python 3.12 + the Lambda execution environment.
|
||||
**Impact if wrong:** Auth Lambda migrates to Fargate, adding ~1 week to P2.
|
||||
**Resolution:** Anchor to **month-only** (August 2026). No specific
|
||||
day in the deck text. November 2026 is the runway anchor (~90 days
|
||||
from August 2026).
|
||||
**Confidence:** 0.95. **Impact if wrong:** Very low — the meeting is
|
||||
what it is; the deck text doesn't depend on a specific day.
|
||||
**Decision:** D-243 (date anchor discipline: month-only).
|
||||
|
||||
### Q2 — PAT revocation propagation latency
|
||||
### Q2 — Explicit non-compression of the existing citizen-developer deck
|
||||
|
||||
The 60-second SLO (NFR-4) depends on whether the token-vend Lambda reads
|
||||
PAT revocation state from DynamoDB on every request (eventually
|
||||
consistent reads) or via a cached/denylist mechanism.
|
||||
**Spec context:** The two decks (leadership + citizen-developer)
|
||||
remain discrete artifacts. The existing 23-slide
|
||||
`nova-autonomous-cloud-delivery-marp.md` is not compressed or
|
||||
modified.
|
||||
|
||||
**Resolution (D-229):** Read-on-every-request with strongly consistent
|
||||
reads on the PAT hash table. Cost is acceptable given expected request
|
||||
volume (token vending is not a hot path — it precedes a deploy, not every
|
||||
request). REV-351 verifies the SLO in CI.
|
||||
**Confidence:** 0.90. **Rationale:** Strongly consistent DynamoDB reads
|
||||
have single-digit-ms latency at expected volume; the 60s SLO has >10x
|
||||
headroom. A cache layer adds invalidation complexity that the SLO does
|
||||
not require.
|
||||
**Impact if wrong:** If read latency exceeds 60s under load, introduce a
|
||||
DynamoDB TTL + cache layer; SLO must be re-verified.
|
||||
**Resolution:** Document the discrete-artifact constraint in
|
||||
REQ-372.9 (related-artifacts header comment) + D-241 (this file) +
|
||||
D-241 record in PROJECT.md at ship (REQ-372.11). Leave the existing
|
||||
citizen-developer deck untouched. The cover note's hard scope rules
|
||||
("Do not modify `nova-autonomous-cloud-delivery-marp.md`") are
|
||||
binding.
|
||||
**Confidence:** 1.0. **Impact if wrong:** None for this milestone.
|
||||
**Decision:** D-241 (restated — the discrete-artifact decision is the
|
||||
same as Q-M3's override).
|
||||
|
||||
### Q3 — JWKS endpoint: Lambda function URL vs. API Gateway
|
||||
### Q3 — Assumption: existing `scripts/render_pptx.py` accepts S&P theme directives and Marp speaker notes without modification
|
||||
|
||||
A function URL is simpler and cheaper but lacks throttling, WAF, and
|
||||
custom domains out of the box.
|
||||
**Spec context:** The render pipeline is existing; the spec assumes
|
||||
it works for the new deck. If a theme limitation forces a renderer
|
||||
change, scope narrowly and update `render_pptx.py` separately as a
|
||||
non-REQ-372 task.
|
||||
|
||||
**Resolution (D-230):** Start with a Lambda function URL behind a custom
|
||||
domain; rate limiting configured at the DNS/CDN layer. API Gateway
|
||||
migration deferred to v1.19+ if throttling requirements grow.
|
||||
**Confidence:** 0.80. **Rationale:** The JWKS endpoint is public-key
|
||||
only (no secrets); the threat surface is low. Function URL + CDN rate-
|
||||
limiting covers the v1.28 volume. API Gateway is over-engineering until
|
||||
traffic patterns are known.
|
||||
**Impact if wrong:** If throttling becomes a requirement, API Gateway
|
||||
migration adds ~3-5 days.
|
||||
**Resolution (confirmed by research):** The existing `render_pptx.py`
|
||||
has two gaps for REQ-372: (a) it expects a `{deck}` arg and reads
|
||||
`{deck}-marp.md` / writes `{deck}-python.pptx` — it does not accept
|
||||
an explicit source path or custom output filename; (b) it does not
|
||||
read the Marp `footer:` directive (it skips HTML comments at lines
|
||||
366-379 and never adds a footer textbox). Speaker notes (HTML
|
||||
comments) are skipped entirely — acceptable for REQ-372.4 (smoke test
|
||||
checks source word counts, not PPTX-embedded notes). The narrow
|
||||
extension per D-242 addresses (a) and (b). No other renderer change
|
||||
is needed. The extension is a prerequisite, scoped separately from
|
||||
REQ-372 per spec §3.3 Edge 2.
|
||||
**Confidence:** 0.92. **Impact if wrong:** Small follow-up; doesn't
|
||||
change milestone scope.
|
||||
**Decision:** D-242 (restated).
|
||||
|
||||
### Q4 — Mode resolver precedence with invalid `NOVA_CLIENT_MODE` value
|
||||
### Q4 — Assumption: the 18-month runway shape (α–δ) is acceptable as drafted to I&O leadership
|
||||
|
||||
What happens if the env var is set to something other than `agent` or
|
||||
`interactive` (e.g., `NOVA_CLIENT_MODE=auto`)?
|
||||
**Spec context:** Slides 6 + 7 rehearse both architecture-load and
|
||||
political-cover framings. The worked-example granularity was
|
||||
confirmed by the PO.
|
||||
|
||||
**Resolution (D-226):** Invalid env var values are ignored, falling
|
||||
through to credential type. A warning is logged. Behavior is documented
|
||||
in the `nova-cli` README. This is a sub-clause of the mode-resolution
|
||||
priority decision.
|
||||
**Confidence:** 0.90. **Rationale:** Ignoring + warning is the least
|
||||
surprising behavior for an operator debugging mode issues. Failing hard
|
||||
would block legitimate workflows that set a stale/typo'd env var.
|
||||
**Impact if wrong:** Operators debugging mode issues may be confused;
|
||||
non-blocking.
|
||||
|
||||
### Q5 — Service-account PAT vs. developer PAT in the same session
|
||||
|
||||
What if both credential types are available (e.g., a developer explicitly
|
||||
exports a service-account PAT)?
|
||||
|
||||
**Resolution (D-226):** The most recently acquired credential wins.
|
||||
Documented in `nova auth login` output. The credential type is what
|
||||
drives mode resolution (INV-14), so the operator sees which mode was
|
||||
selected and why.
|
||||
**Confidence:** 0.85. **Rationale:** "Most recent wins" is the simplest
|
||||
deterministic rule that matches operator mental models of "I just logged
|
||||
in as X." The audit event records the winning credential type, so the
|
||||
selection is traceable.
|
||||
**Impact if wrong:** Mode selection may surprise the operator; non-
|
||||
blocking, but `nova auth status` must make the active credential explicit.
|
||||
|
||||
### Q6 — ABAC policy ownership and versioning
|
||||
|
||||
`platform/abac/token-vend.policy` is referenced, but who owns changes?
|
||||
How are policy versions tracked in audit?
|
||||
|
||||
**Resolution (D-231):** Policy changes require PR review; the policy
|
||||
version (git SHA) is recorded in every token-vend audit event. Owner:
|
||||
Platform Security. The policy file lives in the platform repo at
|
||||
`platform/abac/token-vend.policy` and is reviewed like any other
|
||||
production config.
|
||||
**Confidence:** 0.90. **Rationale:** Git SHA is the natural version
|
||||
identifier for a repo-resident policy; recording it in the audit event
|
||||
makes every allow/deny decision reconstructable to the exact policy text.
|
||||
**Impact if wrong:** Untracked policy changes could lead to unexpected
|
||||
allow/deny decisions in production, undermining audit defensibility.
|
||||
**Resolution:** Accept the α–δ shape as drafted. Slides 6 + 7 are the
|
||||
only slide-by-slide revisions that might be needed if leadership
|
||||
pushes back; everything else is locked. No spec change required
|
||||
unless the architectural claim set shifts (spec §3.3 Edge 3).
|
||||
**Confidence:** 0.85. **Impact if wrong:** Slide 6 and slide 7 are
|
||||
the only revisions; everything else is locked.
|
||||
**Decision:** n/a (acceptance, not a D-ID — the shape is in the
|
||||
locked Slide Content Map).
|
||||
|
||||
---
|
||||
|
||||
## Grounding gaps surfaced in pre-flight (auto-resolved)
|
||||
## Decisions (locked, full autonomy — load-bearing for v1.30)
|
||||
|
||||
### G1 — The `kj` engine does not exist; the spec treats it as locked.
|
||||
### D-241 — Leadership deck is discrete, hand-authored, NOT a compression
|
||||
|
||||
**Resolution (D-227):** The token-vend Lambda uses the existing
|
||||
**kyverno-json** engine (INV-4 swappable) as the ABAC evaluator. The
|
||||
policy at `platform/abac/token-vend.policy` is a kyverno-json policy.
|
||||
No new `kj` engine is built in v1.28. If a distinct `kj` engine is
|
||||
desired later, it is a separate research spike (not this milestone).
|
||||
**Confidence:** 0.95. **Rationale:** The repo already has a swappable
|
||||
policy engine (INV-4) implemented as kyverno-json. Building a second
|
||||
engine to do the same job violates the swappable-engine invariant's
|
||||
spirit. kyverno-json's `evaluate` semantics cover the spec's ABAC needs
|
||||
(subject, claims, resource, environment → allow/deny).
|
||||
**Impact if wrong:** If the user actually wants a new `kj` engine, v1.28
|
||||
scope expands significantly (engine design + implementation + migration).
|
||||
This was flagged as caveat #3 in the approved plan; the recommended path
|
||||
(kyverno-json) is locked here.
|
||||
**Q-M3 / Q2.** The leadership deck is a **discrete, hand-authored
|
||||
artifact** — NOT a compression of the existing 23-slide
|
||||
citizen-developer pitch
|
||||
(`nova-autonomous-cloud-delivery-marp.md`). This overrides the
|
||||
post-v1.29 STATE.md intake assumption 3 ("is a compression, not a
|
||||
rewrite"). The existing citizen-developer deck remains untouched.
|
||||
The spec §2.2 + cover note forbid compression/mirroring; the Slide
|
||||
Content Map is hand-authored content, not derived. Recorded in
|
||||
PROJECT.md at ship (REQ-372.11).
|
||||
**Confidence:** 1.0.
|
||||
|
||||
### G2 — The spec's INV-18..21, INV-34, INV-63/64/65 don't exist.
|
||||
### D-242 — Narrow render_pptx.py extension (path arg + custom output + footer textbox)
|
||||
|
||||
**Resolution:** Re-allocated as **INV-12..INV-17** (see REQUIREMENTS.md
|
||||
§v1.28 Invariants). The 1:1 mapping:
|
||||
- INV-63 (mode observability) → INV-12
|
||||
- INV-64 (mode determinism) → INV-13
|
||||
- INV-65 (credential type encodes role) → INV-14
|
||||
- INV-18..21 (attestation invariants) → INV-15 (no AWS-managed identity),
|
||||
INV-16 (password storage), INV-17 (ABAC discipline). The spec's
|
||||
attestation invariants INV-18..21 are partially covered by existing
|
||||
invariants (INV-6 immutable audit) + INV-17; the JWS-from-PAT behavior
|
||||
(REQ-332) is a requirement, not a separate invariant, in this mapping.
|
||||
- INV-34 (MFA enforcement) → deferred to v1.21+ (out of scope per §2.2);
|
||||
no INV allocated in v1.28.
|
||||
**Confidence:** 0.85. **Rationale:** The mapping preserves the spec's
|
||||
intent without colliding with the repo's INV-1..11. INV-34 (MFA) is
|
||||
explicitly deferred per the spec's own §2.2 out-of-scope table.
|
||||
**Impact if wrong:** If the user wants the exact INV-18..21 semantics as
|
||||
separate invariants, INV-12..17 can be re-numbered; non-blocking.
|
||||
**Q-M2 / Q3.** The existing `scripts/render_pptx.py` is narrowly
|
||||
extended to: (a) accept an explicit source `.md` path + `--output`
|
||||
filename (honouring the cover note's invocation pattern), and (b)
|
||||
render a right-aligned footer textbox on every slide with the exact
|
||||
string `Nova Platform - Infrastructure & Operations` (python-pptx
|
||||
does not read the Marp `footer:` directive; REQ-372.5 requires the
|
||||
footer on every rendered slide). The source is authored as
|
||||
`nova-leadership-deck-marp.md` to fit the existing `-marp.md`
|
||||
pipeline convention; the output is `nova-leadership-deck.pptx` per
|
||||
spec REQ-372.2. This extension is a non-REQ-372 prerequisite per
|
||||
spec §3.3 Edge 2 ("scope narrowly and update `render_pptx.py`
|
||||
separately"). No other renderer change (speaker notes are not
|
||||
embedded in the PPTX — acceptable; smoke test checks source word
|
||||
counts).
|
||||
**Confidence:** 0.92.
|
||||
|
||||
### G3 — The spec's CAP-025..030 collide with blockchain/pilot CAPs.
|
||||
### D-243 — Date anchor discipline: month-only (August 2026 present, November 2026 runway)
|
||||
|
||||
**Resolution:** Re-allocated as **CAP-033..CAP-038** (see REQUIREMENTS.md
|
||||
§v1.28 + REQ-352). The 1:1 mapping:
|
||||
- CAP-025 (CLI subcommand surface) → CAP-033
|
||||
- CAP-026 (subcommand delegates to core/) → CAP-034
|
||||
- CAP-027 (layer matches wheel) → CAP-035
|
||||
- CAP-028 (Nova-idp auth flow) → CAP-036
|
||||
- CAP-029 (token-vend signs via KMS) → CAP-037
|
||||
- CAP-030 (PAT issuance + revocation) → CAP-038
|
||||
**Confidence:** 1.0. **Rationale:** Existing CAP-025..032 are
|
||||
blockchain/pilot capabilities (STATE.md); re-use would corrupt the
|
||||
capability registry. The re-allocated IDs are the next available.
|
||||
**Impact if wrong:** None — this is a numbering decision, not a semantic
|
||||
one.
|
||||
|
||||
### G4 — The spec's REQ-001..031 collide / don't exist.
|
||||
|
||||
**Resolution:** Re-allocated as **REQ-323..REQ-353** (1:1 with the spec's
|
||||
REQ-001..031). Full text in REQUIREMENTS.md §v1.28. Max existing REQ =
|
||||
REQ-322.
|
||||
**Confidence:** 1.0. **Rationale:** Same as G3 — avoid collision, use
|
||||
next available range.
|
||||
|
||||
### G5 — `platform/abac/`, `nova/` subcommand dir, `nova-idp-*` Lambdas don't exist.
|
||||
|
||||
**Resolution:** These are **greenfield deliverables** of v1.28 execution
|
||||
phases, not pre-existing "locked architectures." RESEARCH will design
|
||||
them; PLAN will sequence them; EXECUTE will build them. The spec's
|
||||
"Operating Principle 1" (incremental delivery) is honored — v1.28 is
|
||||
net-new work.
|
||||
**Confidence:** 1.0. **Rationale:** The spec itself describes these as
|
||||
new ("introducing Nova-idp"). The mis-framing was in calling them
|
||||
"locked" — they are locked in *scope*, not in *prior existence*.
|
||||
**Impact if wrong:** None — this is a framing correction.
|
||||
**Q1.** August 2026 is a **month-only** presentation anchor (no
|
||||
specific day). November 2026 is the runway anchor (~90 days from
|
||||
August 2026). Slide 7 references "Infrastructure & Operations
|
||||
leadership" without naming a specific day. No spec change required
|
||||
unless the architectural claim set shifts (spec §3.3 Edge 3).
|
||||
**Confidence:** 0.95.
|
||||
|
||||
---
|
||||
|
||||
## Decision ledger (v1.28 — D-226..D-231)
|
||||
## STATE.md intake assumption override
|
||||
|
||||
| ID | Title | Confidence | Load-bearing for |
|
||||
|----|-------|------------|------------------|
|
||||
| D-226 | Mode resolution priority + invalid-env + dual-credential | 0.90 | REQ-327, INV-12, INV-13, INV-14 |
|
||||
| D-227 | ABAC engine = kyverno-json (no `kj` engine built) | 0.95 | REQ-336, REQ-339, INV-17, NFR-9 |
|
||||
| D-228 | Argon2id in Lambda: bundled wheels + pure-Python fallback + Fargate path | 0.85 | REQ-333, REQ-334, INV-16, NFR-8 |
|
||||
| D-229 | PAT revocation: strongly-consistent DDB read-on-every-request, 60s SLO | 0.90 | REQ-342, REQ-343, REQ-351, NFR-4 |
|
||||
| D-230 | JWKS endpoint: Lambda function URL + custom domain + CDN rate-limit | 0.80 | REQ-338, NFR-5 |
|
||||
| D-231 | ABAC policy ownership: Platform Security, git SHA in audit | 0.90 | REQ-339, NFR-9 |
|
||||
The post-v1.29 STATE.md intake (line ~526, Agent Assumptions, item 3)
|
||||
states: "The 23-slide existing deck is the source material — the
|
||||
≤7-slide leadership deck is a compression, not a rewrite."
|
||||
|
||||
**Override (D-241):** This assumption is **replaced**. The leadership
|
||||
deck is a discrete, hand-authored artifact — NOT a compression. The
|
||||
existing citizen-developer deck remains untouched. The override is
|
||||
recorded in this CLARIFY.md (D-241) and will be reflected in STATE.md
|
||||
at the v1.30 ship wave (CAP-042 row + intake assumption correction).
|
||||
|
||||
---
|
||||
|
||||
## Assumptions logged (full autonomy, no human escalation)
|
||||
## Requirements impact
|
||||
|
||||
1. **CodeArtifact is provisionable** in AWS account `581513795199` (the
|
||||
pilot account). RESEARCH will confirm IAM permissions + repository
|
||||
creation. If not, v1.28 falls back to a private PyPI server or a
|
||||
Gitea-hosted wheel index; the CLI subcommand surface (REQ-324) and
|
||||
identity layer (REQ-333+) are unaffected.
|
||||
2. **Python 3.12** is the target runtime for both the CLI wheel and the
|
||||
Lambda functions (spec §4 REQ-004.3). The repo's current Python
|
||||
version will be confirmed in RESEARCH; if it differs, the CLI pins
|
||||
3.12 and Lambda uses the 3.12 runtime regardless.
|
||||
3. **KMS asymmetric signing** (RSA-2048 or ECDSA P-256) is available in
|
||||
the target account. RESEARCH will confirm. If only symmetric KMS is
|
||||
available, the token-vend Lambda uses symmetric signing + a public-key
|
||||
publication step (less ideal, but functional); INV-15 is unaffected.
|
||||
4. **The Forge action** (REQ-326) is the existing `nova cli-action`
|
||||
pattern, extended to both GitHub and Gitea marketplaces. The repo's
|
||||
current Forge/Gitea workflow conventions (`.gitea/workflows/`,
|
||||
`deploy.yml@v1.25`) are the baseline.
|
||||
5. **MFA/TOTP** code path ships in v1.28 (per spec §2.2) but enforcement
|
||||
for prod/dr is deferred to v1.21+. This is a doc/test-only path in
|
||||
v1.28 — no enforcement gate.
|
||||
|
||||
---
|
||||
|
||||
## CLARIFY complete
|
||||
|
||||
All material ambiguities resolved at full autonomy (6 open questions +
|
||||
5 grounding gaps → D-226..D-231, confidence ≥ 0.80). No human escalation
|
||||
triggered (all confidences ≥ 0.60 threshold). REQUIREMENTS.md updated
|
||||
with the decision ledger + invariants. Next: RESEARCH.
|
||||
|
||||
---
|
||||
|
||||
# CLARIFY — v1.29 Reposplit + Identity Layer Bring-Live
|
||||
|
||||
> **Autonomy:** full. Auto-resolution with assumption logging per
|
||||
> `config.autonomy.level: "full"`. No human escalation unless confidence
|
||||
> < 0.60. The v1.29 spec is v1.1 (highly detailed — §7 resolves Q1-6, Q7
|
||||
> carried forward as a verification-gate dependency). This file records
|
||||
> the v1.29 ambiguities and the scope-split grounding.
|
||||
|
||||
---
|
||||
|
||||
## Method
|
||||
|
||||
The v1.29 spec ("Universal Feature Specification — Reposplit + Identity
|
||||
Layer Bring-Live", v1.1) is the most detailed spec the project has
|
||||
received: it includes BDD acceptance criteria, an 8-item M1.5 spike
|
||||
checklist, 7 decisions pre-drafted (D-232..238), 14 NFRs, and an
|
||||
explicit §7 resolving Q1-6. Clarify work focuses on (a) the scope split
|
||||
between `acdl` (CIAgent) and `nova-platform-ops` (out-of-band), (b) the
|
||||
`kj` identity (Go binary vs. the v1.28 kyverno-json re-mapping), and (c)
|
||||
the carried-forward Q7. Each ambiguity gets a decision ID (D-232+,
|
||||
continuing from v1.28's D-226..D-231), a resolution, a confidence score,
|
||||
and a rationale.
|
||||
|
||||
---
|
||||
|
||||
## Prior-conversation resolutions (already locked, restated for the record)
|
||||
|
||||
These were resolved by the user-approved execution plan in the
|
||||
conversation that spawned v1.29.
|
||||
|
||||
### Q-P1 — The spec creates a separate repo `nova-platform-ops`. CIAgent runs inside `acdl`. Where does the Terraform code land?
|
||||
|
||||
**Resolution:** Terraform modules
|
||||
(`networking`/`kms`/`identity`/`contract-ingest`/`bootstrap`/`edge`) are
|
||||
authored **out-of-band** in `nova-platform-ops` (operator-owned). CIAgent
|
||||
in `acdl` delivers only the acdl-side work (publish.yml, Gitea scrub,
|
||||
CFN archive, operator guide, consumer bump) and tracks the ops-side
|
||||
REQs as **covered-reference** (verification surface = the M1/M1.5/M2
|
||||
cutover gates documented in the operator guide).
|
||||
**Confidence:** 1.0 (user-confirmed — "Author out-of-band in
|
||||
nova-platform-ops"). **Decision:** scope split documented in
|
||||
PROJECT.md §v1.29 + REQUIREMENTS.md §v1.29.
|
||||
|
||||
### Q-P2 — The run scope. How far does this `/ci-run` go?
|
||||
|
||||
**Resolution:** Full milestone through the final phase (P0 → P1..P5 →
|
||||
P6 final review + audit + milestone ship, tag `v1.28.6`).
|
||||
**Confidence:** 1.0 (user-confirmed — "Full milestone through final
|
||||
phase"). **Decision:** n/a (execution scope, not a D-ID).
|
||||
|
||||
### Q-P3 — Edge 8 / REQ-354 footnote: pilot consumer deploy bump. Handle how?
|
||||
|
||||
**Resolution:** Include a cross-project phase (P5) in this CIAgent run
|
||||
(multi-project mode is active). Bump `nova-blockchain-exchange`
|
||||
deploy.yml `@v1.25` → `@v1.29` + smoke test.
|
||||
**Confidence:** 1.0 (user-confirmed — "Cross-project phase in this
|
||||
run"). **Decision:** n/a (execution scope).
|
||||
|
||||
---
|
||||
|
||||
## Spec-grounded resolutions (from §7 + §5)
|
||||
|
||||
### Q1 — State bucket bootstrap on day-0 (resolved per spec §7.1)
|
||||
|
||||
**Resolution:** Manual one-time at the operator's secure scratch; Terraform
|
||||
then adopts it via `terraform import`. Avoids bootstrapping the
|
||||
bootstrapper. **Confidence:** 1.0 (spec §7.1 explicit). **Decision:**
|
||||
D-235 (tag-pin handoff) — the state bucket is one of the imported
|
||||
resources.
|
||||
|
||||
### Q2 — `pyproject.toml` version bump (resolved per spec §7.2)
|
||||
|
||||
**Resolution:** Bump to `1.29.0` in M1 (P2 — Gitea scrub phase) of v1.29
|
||||
alongside the Gitea scrub. **Confidence:** 1.0 (spec §7.2 explicit).
|
||||
**Decision:** n/a (implementation detail, tracked in PLAN.md P2).
|
||||
|
||||
### Q3 — WAF cost (resolved per spec §7.3)
|
||||
|
||||
**Resolution:** Acceptable for the JWKS public surface; documented in
|
||||
operator-guide cost section (~$5–10/month per WebACL + per-request).
|
||||
**Confidence:** 1.0 (spec §7.3 explicit). **Decision:** documented in
|
||||
REQ-OPS-GUIDE AC.
|
||||
|
||||
### Q4 — Coverage 73.8% — does this milestone drive it down further? (resolved per spec §7.4)
|
||||
|
||||
**Resolution:** Accept any further debt as carry-forward to the separate
|
||||
NFR milestone. New modules have ≥80% coverage; older code paths are
|
||||
unchanged. YELLOW carried without scope expansion. **Confidence:** 1.0
|
||||
(spec §7.4 explicit). **Decision:** n/a (NFR carry-forward, not a v1.29
|
||||
D-ID).
|
||||
|
||||
### Q5 — CFN code deletion timing (resolved per spec §7.5)
|
||||
|
||||
**Resolution:** Archive to `docs/archive/nova-idp-cfn-v1.28.md`; deletion
|
||||
is a follow-up after the next pilot run verifies Terraform parity.
|
||||
**Confidence:** 1.0 (spec §7.5 explicit). **Decision:** REQ-369 AC (3).
|
||||
|
||||
### Q6 — `acdl-act-runner-role` reuse (resolved per spec §7.6)
|
||||
|
||||
**Resolution:** Reuse the existing role for v1.29 to minimize IAM surface
|
||||
changes; scope narrow per REQ-360. **Confidence:** 1.0 (spec §7.6
|
||||
explicit). **Decision:** covered by REQ-360 (IAM-NARROW).
|
||||
|
||||
### Q7 — `kj` image verification dependency (CARRY-FORWARD per spec §7.7)
|
||||
|
||||
**Resolution (carry-forward):** M1 cutover is conditional on the M1.5
|
||||
verification gate. **Recommendation:** Block M1 cutover until M1.5
|
||||
passes. If M1.5 fails three consecutive rebuilds, defer to M2a and ship
|
||||
Nova-idp in read-only partial mode (no token issuance) until `kj` is
|
||||
verified. **Impact if wrong:** A live token-vend that signs with a
|
||||
broken ABAC path would let through a denied claim — fails closed only if
|
||||
`ImageUri` is verified pre-apply. **Confidence:** 0.92 (spec §7.7
|
||||
explicit + D-236 cutover shape). **Decision:** D-236 (cutover shape +
|
||||
rollback procedure). This is the **only** outstanding carry-forward;
|
||||
CIAgent in acdl builds + publishes the image + the gate tests (P1), but
|
||||
the live 3-rebuild verification happens in `nova-platform-ops` CI
|
||||
(out-of-band). CIAgent does not block on it.
|
||||
|
||||
---
|
||||
|
||||
## Grounding-gap resolutions (surfaced in pre-flight)
|
||||
|
||||
### G1 — The spec's `kj` vs. v1.28's `kj` re-mapping
|
||||
|
||||
**Ambiguity:** v1.28 (D-227) re-mapped the spec's `kj` engine →
|
||||
kyverno-json (INV-4 swappable), explicitly stating "no new `kj` engine
|
||||
is built." v1.29 reintroduces `kj` as a compiled Go binary
|
||||
(`platform/abac/kj-version.txt`, pinned v0.0.3) embedded in an ECR
|
||||
container image. Is this a contradiction?
|
||||
|
||||
**Resolution:** No contradiction. v1.28's `kj` was a *policy engine*
|
||||
reference; v1.29's `kj` is a *compiled Go binary* (a distinct artifact).
|
||||
The kyverno-json engine remains the policy engine (INV-4). The v1.29
|
||||
`kj` binary is invoked via `subprocess.run(['/opt/kj/kj', 'apply', ...])`
|
||||
by the Lambda handler — it is a **substrate** binary, not a policy
|
||||
engine. The two coexist: kyverno-json evaluates ABAC policy; `kj` is the
|
||||
container image's static binary that the Lambda runtime executes. No
|
||||
collision.
|
||||
**Confidence:** 0.95 (spec §3.3 Edge 5 item 4 explicit + v1.28 D-227
|
||||
scope). **Decision:** documented in PROJECT.md §v1.29 ID allocations +
|
||||
KJ-STATIC NFR.
|
||||
|
||||
### G2 — `REQ-363b` sub-requirement numbering
|
||||
|
||||
**Ambiguity:** The spec uses `REQ-363b` for the Fargate defensive
|
||||
fallback. The repo's REQ namespace is `REQ-NNN` (numeric). How to
|
||||
record `363b`?
|
||||
|
||||
**Resolution:** Keep `REQ-363b` as-is (sub-requirement of REQ-363). It
|
||||
is a distinct requirement (Fargate fallback, KJ-LOCKSTEP) but logically
|
||||
paired with REQ-363 (production substrate). The `b` suffix is
|
||||
unambiguous and matches the spec. No collision with any existing REQ.
|
||||
**Confidence:** 0.98 (spec explicit + no collision). **Decision:** n/a
|
||||
(naming convention).
|
||||
|
||||
### G3 — `REQ-370` gap
|
||||
|
||||
**Ambiguity:** The spec jumps from REQ-369 to REQ-371. Is REQ-370
|
||||
missing or intentionally unused?
|
||||
|
||||
**Resolution:** Intentionally unused per the source spec. REQ-370 is a
|
||||
gap in the spec's numbering (likely a deleted/renumbered item during
|
||||
spec v1.0 → v1.1). v1.29 does not allocate REQ-370; it remains a
|
||||
reserved gap. **Confidence:** 0.90 (spec explicit gap, no content).
|
||||
**Decision:** n/a (spec fidelity).
|
||||
|
||||
### G4 — Covered-reference REQs and CIAgent verification
|
||||
|
||||
**Ambiguity:** REQ-355, 356, 357, 358, 359, 360, 361, 362, 363, 363b,
|
||||
364, 365, 366, 371 are authored in `nova-platform-ops` (out-of-band).
|
||||
How does CIAgent verify them? Are they `human_needed`?
|
||||
|
||||
**Resolution:** They are **covered-reference**, NOT `human_needed`. The
|
||||
verification surface is the M1/M1.5/M2 cutover gates documented in the
|
||||
operator guide (`docs/operator-guide-platform-ops.md`). The operator
|
||||
guide lists each covered-reference REQ with its cutover gate entry
|
||||
(M1/M1.5/M2). CIAgent verify marks them `covered-reference` and the
|
||||
final-phase audit confirms the operator guide documents all gates.
|
||||
**Confidence:** 0.94 (scope-split decision + spec §2.3 milestone
|
||||
gates). **Decision:** documented in REQUIREMENTS.md §v1.29 + REQ-OPS-
|
||||
GUIDE AC.
|
||||
|
||||
---
|
||||
|
||||
## Assumptions (logged, not escalated — confidence ≥ 0.80)
|
||||
|
||||
1. **`kj` v0.0.3** is available at the pinned SHA in
|
||||
`platform/abac/kj-version.txt` and compiles with `CGO_ENABLED=0
|
||||
GOOS=linux GOARCH=amd64`. RESEARCH will confirm the source repository
|
||||
+ build commands. If the binary is not available, P1 (publish
|
||||
pipeline) cannot produce the ECR image; M1.5 gate fails by
|
||||
construction → M2a (Fargate toggle, same image) also fails → escalate
|
||||
(but this is a spec dependency, not a CIAgent ambiguity).
|
||||
2. **ECR repository** exists or is creatable in account `581513795199`
|
||||
for the `kj` image. RESEARCH will confirm. The repo name is not
|
||||
specified in the spec; the operator guide will document it.
|
||||
3. **GitHub Releases** is the artifact distribution channel (per
|
||||
REQ-354). The `acdl/acdl` repo is already on GitHub (the Gitea scrub
|
||||
in REQ-367 standardizes on GitHub). NOVA_FORGE_TOKEN (Gitea) is
|
||||
retained for `nova-platform-ops` releases only.
|
||||
4. **The `nova idp setup --apply` terraform-delegation** (REQ-369 AC 2)
|
||||
requires `terraform` to be on the operator's PATH. The CLI detects
|
||||
terraform via `which terraform`; if absent, it falls back to the CFN
|
||||
path with a deprecation warning (the CFN archive remains read-only
|
||||
reference, but the delegation is the preferred path).
|
||||
5. **The M1.5 8-item spike** (spec §3.3 Edge 5) is the verification
|
||||
gate. CIAgent in acdl authors the *tests* (test_idp_auth,
|
||||
test_kms_roundtrip, ABAC E2E) in P1; the *live 3-rebuild run*
|
||||
happens in `nova-platform-ops` CI. This is the Q7 carry-forward
|
||||
surface.
|
||||
|
||||
---
|
||||
|
||||
## CLARIFY complete
|
||||
|
||||
All material ambiguities resolved at full autonomy (3 prior-conversation
|
||||
+ 7 spec-grounded + 4 grounding-gap → D-232..D-238, confidence ≥ 0.80).
|
||||
Q7 is the only carry-forward (verification-gate dependency, not a
|
||||
blocking ambiguity). No human escalation triggered (all confidences ≥
|
||||
0.60 threshold). REQUIREMENTS.md updated with the decision ledger +
|
||||
invariants + NFR constraints. Next: RESEARCH.
|
||||
No requirements are added, removed, or re-scoped by these decisions.
|
||||
D-241–D-243 are load-bearing context for executing REQ-372.1–.12 as
|
||||
written. The spec is locked (v1.0, 2026-08-20); no spec text changes.
|
||||
+1
-1
@@ -523,7 +523,7 @@ Known Tensions: (1) nova-platform-ops repo not yet created — the 14 covere
|
||||
|
||||
Missing Context: (1) The 18-month roadmap specifics — NORTH_STAR.md §Future Horizons has the strategic direction (CDLC→SDLC→PDLC integration, AI-Agent Intent Share ≥40%) but the PO needs to define the concrete milestone sequence for the deck. (2) Target audience specifics — "Technology Leadership" is the stated audience but the deck needs to know if this is CTO-level, VP-level, or Director-level (affects depth + framing). (3) Live AWS verification of covered-reference REQs — nova-platform-ops not yet created; M1/M1.5/M2 cutover gates not yet run.
|
||||
|
||||
Agent Assumptions: (1) The PDLC trigger is the post-v1.29 state intake + the PO's new initiative (leadership deck). (2) The deck uses the existing S&P theme (`docs/presentations/assets/nova-sp-theme.css`, palette `#D6002A`/`#1B1B1B`/`#FFFFFF`/`#F0F0F0`) + the existing Marp + python-pptx render pipeline (`workflows-src/slides.yml`, `scripts/render_pptx.py`). (3) The 23-slide existing deck is the source material — the ≤7-slide leadership deck is a compression, not a rewrite. (4) Coverage 73.8% is reported as YELLOW system health (below 80% floor) but is not a blocker for the deck initiative — it's quality debt for a future NFR milestone. (5) The covered-reference REQs are reported as tensions, not blockers — they have acdl-side deliverables complete + documented cutover gates.
|
||||
Agent Assumptions: (1) The PDLC trigger is the post-v1.29 state intake + the PO's new initiative (leadership deck). (2) The deck uses the existing S&P theme (`docs/presentations/assets/nova-sp-theme.css`, palette `#D6002A`/`#1B1B1B`/`#FFFFFF`/`#F0F0F0`) + the existing Marp + python-pptx render pipeline (`workflows-src/slides.yml`, `scripts/render_pptx.py`). (3) **OVERRIDDEN by D-241 (v1.30 CLARIFY):** the leadership deck is a **discrete, hand-authored artifact — NOT a compression** of the 23-slide existing citizen-developer deck (`nova-autonomous-cloud-delivery-marp.md`), which remains untouched. The Slide Content Map in PROJECT.md §v1.30 is hand-authored content, not derived. (4) Coverage 73.8% is reported as YELLOW system health (below 80% floor) but is not a blocker for the deck initiative — it's quality debt for a future NFR milestone. (5) The covered-reference REQs are reported as tensions, not blockers — they have acdl-side deliverables complete + documented cutover gates.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user