fix(wardens): distinguish OPA ledger staleness from a real review gap (LIA-535) (#1161)

## Summary
- `guardrails.rego`'s file-level `default decision` message ("guardrails
policy produced no valid decision") fired identically for a genuine
missing-review-attestation denial and for a transient OPA ledger
generation mismatch (disk/OPA desync, self-heals within 5 min via
LIA-533's periodic job) — no hint to a developer that the cause might be
infra staleness, not "you need a SHIP."
- New `decision` rule fires a distinct, actionable message specifically
for the generation-mismatch case, scoped to `git.commit`/`file.write`
(the two operations whose decision bodies all require `supported`).
`attestation.verify` is explicitly excluded — it already has its own
composite deny message, and including it would create a real Rego
`eval_conflict_error` (verified by mutation testing).
- Folds in a one-line fix to an adjacent, already-stale ticket citation
(was `LIA-534`, corrected to `LIA-539` — `LIA-534`/`LIA-531` are both
Done/merged; `LIA-539` is the actual open ticket gating
`main-attestation-backstop`'s activation, independently re-verified
against live Linear state rather than the ADR, which itself still lags
on this point).

## Test plan
- [x] `opa test -v --ignore="*.schema.json"
scripts/warden_policy/policy` → 68/68 pass (65 existing + 3 new)
- [x] `opa check --strict scripts/warden_policy/policy` → clean
- [x] `python3 -m pytest scripts/warden_policy/tests` → 303 passed, 1
skipped, 65 subtests, zero regressions
- [x] Mutation-tested the exclusion guard: dropping it entirely
reproduces a real `eval_conflict_error`; the new test catches it
- [x] plan-reviewer: 3 rounds (round 1 REVISE — guard was too broad, `!=
"attestation.verify"` would misclassify unrecognized operations as
staleness, caught via a live failing-test reproduction; round 2 REVISE —
wrong ticket citation; round 3 SHIP after independent live-Linear +
doc-timestamp re-verification), Claude + GPT co-gate
- [x] code-reviewer SHIP (Claude + GPT; GLM `COULD_NOT_RUN` on quota
exhaustion, fails open per established precedent)
- [x] ai-eng-warden SHIP (gate-spec file; confirmed reason-string-only
change, no allow/deny regression, no attacker-controllable input,
accurate remediation hint)
- [x] verification-gate: 4 rounds — caught 2 real comment-accuracy
defects (a misleading counterfactual claim in a test comment, a
stale-doc pointer that would lead a reader back into the exact misread
`LIA-539` was filed to prevent, plus one wrong-direction
cross-reference), all fixed and re-verified; final SHIP

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: sliamh11

scripts/warden_policy/policy/guardrails.rego

@@ -13,14 +13,41 @@ default decision := {"allow": false, "reason": "guardrails policy produced no va
 # `supported` gates every non-default decision below. Found missing by adversarial plan-review:
 # an unrecognized root schema_version, an unrecognized input contract_version, or OPA serving a
 # stale ledger snapshot (generation mismatch, e.g. after a failed/ambiguous PUT even though OPA
-# itself is reachable) must all fall through to the default deny, not be silently accepted by a
-# rule that only checked the individual attestation record's own schema_version.
+# itself is reachable) must all fall through to a deny, not be silently accepted by a rule that
+# only checked the individual attestation record's own schema_version. For `git.commit`/
+# `file.write` operations specifically, a generation mismatch gets its own dedicated message
+# (see the decision rule right below `supported`, LIA-535) rather than the fully generic default
+# at the top of this file -- every other `not supported` cause, and every other/unrecognized
+# operation, still falls through to that generic default unchanged.
 supported if {
 	input.contract_version == 1
 	data.warden_attestations.schema_version == 1
 	data.warden_attestations.generation == input.expected_generation
 }
 
+# Distinguishes ledger staleness (self-healing infra desync, LIA-533) from every other
+# `supported`-gated denial and from the fully generic default above (LIA-535). Scoped to exactly
+# the two operations whose decision bodies all require `supported` (git.commit, file.write) --
+# NOT `input.operation != "attestation.verify"`, which would also swallow any unrecognized/future
+# operation value and misreport it as ledger staleness (caught by plan-review round 1). Excludes
+# attestation.verify specifically because that operation already has its own dedicated composite
+# deny message (below) covering "no SHIP found ... or OPA snapshot stale/unsupported" for BOTH
+# ledgers -- letting this rule also match attestation.verify inputs would create a genuine
+# multi-value `decision` conflict (OPA eval_conflict_error) whenever both conditions hold
+# simultaneously, which they can.
+decision := {
+	"allow": false,
+	"reason": sprintf(
+		"OPA ledger generation stale (expected %d, got %d) -- run `python3 scripts/warden_attest.py sync` or wait for the next self-heal tick (LIA-533)",
+		[input.expected_generation, data.warden_attestations.generation],
+	),
+} if {
+	input.operation in {"git.commit", "file.write"}
+	input.contract_version == 1
+	data.warden_attestations.schema_version == 1
+	data.warden_attestations.generation != input.expected_generation
+}
+
 enrolled if data.warden_attestations.config.enforced_repos[input.repo_id].enabled
 
 # `latest["code-review"]` is a pointer, not a trusted authority on its own -- every field the
@@ -234,8 +261,11 @@ decision := {
 # gpt/glm co-gate backends -- permanent, by-design limitation, disclosed here and in the allow
 # reason string. No signing, no runner isolation -- same-host trust, same accepted-risk framing
 # as git-level-hard-backstop-design.md §3.3. A DENY is authoritative-to-block; an ALLOW means
-# "evidence found," never "fully reviewed." **DOES NOT ACTIVATE UNTIL LIA-534's gate-wiring lands
-# too -- see git-level-hard-backstop-design.md §3.6's corrected three-part precondition.**
+# "evidence found," never "fully reviewed." **DOES NOT ACTIVATE UNTIL LIA-539 (the credential-
+# separation implementation) lands -- LIA-531 merged as DESIGN ONLY and does not clear this gate
+# on its own; confirmed live via LIA-539's own Linear description, not via
+# git-level-hard-backstop-design.md §5, which is stale on this specific point as of this writing
+# (still cites LIA-531 alone -- needs its own follow-up, out of scope here).**
 
 cc_supported if {
 	input.contract_version == 1

scripts/warden_policy/policy/guardrails_test.rego

@@ -167,6 +167,24 @@ test_deny_stale_opa_generation_mismatch if {
 	not decision.allow with input as inp with data.warden_attestations as base_attestations
 }
 
+# LIA-535: git.commit/file.write generation mismatches get a distinct, diagnostic reason instead
+# of the fully generic default -- proves the new decision body actually fires with the right text,
+# not just that allow is false (test_deny_stale_opa_generation_mismatch above only checks that).
+test_deny_stale_opa_generation_mismatch_has_distinct_reason if {
+	inp := object.union(base_input(subject_reviewed), {"expected_generation": 4})
+	decision.reason == "OPA ledger generation stale (expected 4, got 5) -- run `python3 scripts/warden_attest.py sync` or wait for the next self-heal tick (LIA-533)" with input as inp with data.warden_attestations as base_attestations
+}
+
+# LIA-535 round-1 regression test: an unrecognized operation with a stale expected_generation must
+# still fall through to the fully generic default, not get misclassified as ledger staleness. This
+# is the exact scenario plan-review round 1 caught against the original, too-broad
+# `input.operation != "attestation.verify"` guard.
+test_deny_unrecognized_operation_with_stale_generation_still_hits_generic_default if {
+	inp := object.union(base_input(subject_reviewed), {"operation": "something.else", "expected_generation": 4})
+	not decision.allow with input as inp with data.warden_attestations as base_attestations
+	decision.reason == "guardrails policy produced no valid decision" with input as inp with data.warden_attestations as base_attestations
+}
+
 test_deny_malformed_store_missing_records_key if {
 	att := {
 		"schema_version": 1, "generation": 5,
@@ -614,6 +632,23 @@ test_attestation_verify_deny_stale_hermes_generation_with_real_ship_present if {
 	not decision.allow with input as inp with data.warden_attestations as base_attestations with data.warden_cc_attestations as base_cc_attestations
 }
 
+# LIA-535 exclusion-proof: attestation.verify must NOT match the new git.commit/file.write-scoped
+# generation-mismatch rule -- it keeps its own composite deny message. This also proves there's no
+# Rego eval_conflict_error: if the new rule's `input.operation in {...}` guard were dropped
+# entirely, this exact input would satisfy BOTH the new rule's condition and the existing
+# attestation.verify fallback's `not hermes_path_ok, not cc_path_ok` condition simultaneously, and
+# `opa test` would report eval_conflict_error for this test rather than PASS/FAIL. (The round-1-
+# rejected `!= "attestation.verify"` guard does NOT trigger this specific conflict -- it still
+# excludes attestation.verify correctly; its bug was misclassifying unrecognized operations
+# instead, covered by test_deny_unrecognized_operation_with_stale_generation_still_hits_generic_default above.)
+test_attestation_verify_stale_hermes_generation_keeps_composite_message if {
+	inp := object.union(attestation_verify_input(subject_cc_mirrored), {"expected_generation": 4})
+	decision.reason == sprintf(
+		"no SHIP found for %s (Hermes-native or Claude-Code-mirrored; or an explicit non-SHIP Hermes verdict exists; or OPA snapshot stale/unsupported)",
+		[subject_cc_mirrored],
+	) with input as inp with data.warden_attestations as base_attestations with data.warden_cc_attestations as base_cc_attestations
+}
+
 test_attestation_verify_allow_hermes_native_precedence_when_cc_evidence_also_exists if {
 	# Code-reviewer finding: no fixture previously had BOTH a fresh Hermes SHIP and a valid
 	# CC-mirrored SHIP for the SAME subject -- the normal production state once LIA-534 lands (a