acdl/.ciagent/CLARIFY.md

# CLARIFY — v1.25 kyverno-json Unified Policy Engine

> **Autonomy:** full. Ambiguities are auto-resolved with assumption logging
> per `config.json autonomy.level: "full"` and
> `autonomy.decision_confidence_threshold: 0.6`. No human escalation.

## Ambiguities Identified

### A1 — kyverno-json install path (pip / go install / pinned binary release)

**Ambiguity:** kyverno-json is a Go project, not a Python package. Three
install paths exist: (a) `pip install` — not possible (no PyPI package);
(b) `go install github.com/kyverno/kyverno-json/cmd/kj@latest` — requires
Go toolchain in the CI image; (c) download a pinned binary release from
GitHub releases — no Go toolchain needed, but release artifacts are
platform-specific and must be checksummed.

**Resolution (auto, confidence 0.85):** `go install` (option b). A
`scripts/install-kyverno-json.sh` helper runs
`go install github.com/kyverno/kyverno-json/cmd/kj@latest` and prints
`kj version`. The CI image (`.github/workflows/ci.yml` +
`.gitea/workflows/ci.yml`) installs Go + kj when
`config.json.policy.engine == "kyverno-json"`; the install is cached via
the existing Go module cache. Rationale: `go install` is the upstream-
blessed path, tracks the latest stable release, avoids per-platform
binary management, and the project already accepts Go-based tooling
(checkov pulls Go-built transitive deps via pip). When `which kj` is
absent, `KyvernoJsonEngine.is_configured()` returns false → `SKIPPED`
PCR (mirrors the Wiz adapter pattern) — the platform functions without
the binary. Captured in REQ-293, REQ-294. Decision ID: D-115.

### A2 — `engine` enum value: new `"kyverno-json"` vs reuse `"kyverno"`

**Ambiguity:** `schemas/policy_check_result.schema.json` already lists
`engine: ["checkov", "kyverno", "opa", "wiz"]`. kyverno-json is a
distinct runtime from the K8s Kyverno admission controller, but both
are "Kyverno." Two options: (a) add a new `"kyverno-json"` enum value
— requires schema change + checkov/wiz adapter test regression check;
(b) reuse `"kyverno"` and distinguish by `ruleId` prefix.

**Resolution (auto, confidence 0.80):** Reuse `"kyverno"` (option b).
Adding `"kyverno-json"` would force a schema change + a test sweep for
no semantic gain — the `engine` field records the policy engine family,
not the specific binary. kyverno-json PCR records carry `engine:
"kyverno"` and `ruleId` prefixed `KJ_<policy_name>` (e.g.
`KJ_REQUIRE_TAGGING_STANDARD`), while the K8s adapter uses `KYVERNO_`
prefixes (e.g. `KYVERNO_INACTIVE_TF_STACK`). The two are distinguishable
in audit/telemetry by `ruleId` prefix and `evidence` payload shape (the
K8s adapter's evidence has `namespace`/`kind`; kyverno-json's has
`assertion`/`jmespath`). No schema change. Captured in REQ-293.
Decision ID: D-116.

### A3 — Do checkov/wiz adapters change their signatures to feed kyverno-json?

**Ambiguity:** The unified-orchestrator model places kyverno-json "on
top of" checkov/wiz. Two interpretations: (a) checkov/wiz now emit a
"raw findings" intermediate (not PCR) that kyverno-json meta-policies
consume — requires changing `adapt() -> list[PolicyCheckResult]` to
`adapt() -> list[RawFinding]`; (b) checkov/wiz keep emitting PCRs as
today, and the meta-policies in `adapters/kyverno-json/policies/meta/`
consume the **merged** PCR list as their payload.

**Resolution (auto, confidence 0.90):** Option (b). The existing
`adapt() -> list[PolicyCheckResult]` signatures are unchanged. The
meta-policies consume the merged PCR list (checkov + wiz + kyverno-json
plan-JSON policies) as their input payload. This preserves the
`PolicyCheckResult` schema as the single inter-adapter contract
(ARCHITECTURE.md §12.6), avoids a new "RawFinding" type, and means
the existing checkov/wiz adapter tests pass unchanged. The meta-policy
`block-on-any-critical.json` iterates the merged list; the
`tagging-rules-agree.json` meta-policy cross-checks the Checkov
`NOVA_TAG_NAMING` result against the kyverno-json
`KJ_REQUIRE_TAGGING_STANDARD` result by `resourceRef`. Captured in
REQ-303, D-117. Decision ID: D-117.

### A4 — `NOVA_TAG_NAMING` Checkov rule: rewrite as kyverno-json policy, keep, or both?

**Ambiguity:** The Checkov custom rule
`adapters/terraform/policy/custom_rules/nova_tagging.py` enforces the
Nova tagging standard over Terraform HCL (static scan + plan scan). The
kyverno-json milestone adds `require-tagging-standard.json` over the
resolved Stack IR. Three options: (a) rewrite — replace the Checkov
rule with the kyverno-json policy (loses Checkov's HCL-level coverage
and the `--external-checks-dir` integration); (b) keep Checkov only —
don't add a kyverno-json policy (the Stack IR is already the input to
terraform, so the Checkov rule catches it); (c) both — keep the
Checkov rule as the source of truth for HCL-level scanning AND add the
kyverno-json policy for IR-level coverage, with a meta-policy that
asserts the two agree.

**Resolution (auto, confidence 0.82):** Option (c) — both, with a
cross-check meta-policy. The Checkov rule stays the source of truth
for `terraform_plan` scanning (it reads HCL resource blocks directly);
the kyverno-json policy covers the Stack IR dict (which is the input
*before* terraform, so it catches IR-level violations that the
terraform adapter might mask via defaults). The P3 meta-policy
`tagging-rules-agree.json` asserts the two engines agree on every
resource; divergence emits an `error` PCR (defense-in-depth against
rule drift — if the two engines disagree, the operator must
investigate before proceeding). This is the only case in v1.25 where
two engines evaluate the same concern; it is intentional — the
tagging standard is the highest-impact rule (v1.8 D-tagging-standard,
v1.10 re-verification) and merits redundancy. Captured in REQ-297,
REQ-303, REQ-299. Decision ID: D-118.

### A5 — Critical-override: delegate to declarative meta-policy or keep hard-override?

**Ambiguity:** `core/confidence_signal.py` lines 144-157 hardcode
`PENALTY["critical"]: None` — a critical-severity `fail` PCR forces
`score = 0, band = block` regardless of the weighted-sum inputs. The
v1.25 meta-policy `block-on-any-critical.json` makes this declarative
(asserts no PCR in the merged list has `severity: critical` +
`result: fail`). Two options: (a) fully delegate — remove the
hard-override, rely on the meta-policy to emit a critical `fail` PCR
that the existing penalty logic then blocks; (b) keep both — the
meta-policy is the declarative source of truth, the hard-override is
defense-in-depth.

**Resolution (auto, confidence 0.88):** Option (b) — keep both. The
meta-policy is the *declarative* statement ("Nova blocks on any
critical finding from any engine"); the hard-override is the
*imperative* safety net that ensures a critical PCR can never slip
through even if the meta-policy is misconfigured or the
`PolicyEngineRegistry` returns a `NullEngine`. This is
defense-in-depth, not redundancy-for-its-own-sake: the meta-policy
runs *before* the confidence signal (it produces PCRs that flow in),
the hard-override runs *inside* the confidence signal (it is the last
gate). Removing the hard-override would make the platform's
"critical = block" guarantee depend on a single declarative policy
file — a regression in the provable-trust posture (Strategic
Objective #2). Captured in REQ-303, PROJECT.md hard-constraints.
Decision ID: D-119.

### A6 — Does kyverno-json break the "platform functions without AI" tenet?

**Ambiguity:** NORTH_STAR.md Strategic Objective #2: "the platform
functions without AI — 'AI decisions' are really automated decisions."
kyverno-json is a deterministic policy engine (no ML), but it is a new
runtime dependency. Does adding it violate the tenet?

**Resolution (auto, confidence 0.95):** No — kyverno-json is
deterministic, not AI. The tenet distinguishes "AI decisions" (LLM-
driven, non-reproducible) from "automated decisions" (rule-driven,
reproducible). kyverno-json is the latter — the same policy + payload
produces the same result on every run. It is *more* aligned with the
tenet than the current imperative Python in `core/env_transition.py`
and `core/regression_verify.py`, because the policy is declarative
(visible, auditable, version-controlled) rather than imperative (logic
hidden in function bodies). The `is_configured()` guard ensures the
platform functions without the binary (graceful skip), so the tenet
holds even in environments where kyverno-json is not installed.
Captured in PROJECT.md hard-constraints + RESEARCH.md G-Q1.
Decision ID: D-120.

## Summary

6 ambiguities identified; 6 auto-resolved at full autonomy (no human
escalation). All resolutions are binding and recorded as D-115..D-120.
The resolutions are captured in PROJECT.md hard-constraints,
REQUIREMENTS.md v1.25 sections, and will be referenced in RESEARCH.md +
PLAN.md. No PROJECT.md or REQUIREMENTS.md structural changes beyond the
v1.25 sections added in SPECIFY — the resolutions are already embedded
in the requirement text (REQ-293, REQ-297, REQ-303, etc.) via the
"Decision" annotations.