Skip to content

Require opt-in for scale and normalization overrides - #8

Merged
tmusser merged 15 commits into
mainfrom
agent/require-scale-normalization-opt-in
Aug 16, 2026
Merged

Require opt-in for scale and normalization overrides#8
tmusser merged 15 commits into
mainfrom
agent/require-scale-normalization-opt-in

Conversation

@tmusser

@tmusser tmusser commented Aug 16, 2026

Copy link
Copy Markdown
Owner

What changed

  • add a deterministic spec policy that blocks quantitative scale overrides unless usermeta.user_requested_scale_override=true is explicitly declared
  • block native Vega-Lite normalization unless usermeta.user_requested_normalization=true is explicitly declared
  • keep ordinary untouched scale defaults authorization-free
  • preserve the existing hard failure for scale.zero=false on quantitative bars
  • additionally block explicit numeric bar domains that exclude zero even when a scale override was user-requested
  • route both the public Python audit_spec() API and CLI gate through the policy wrapper
  • add focused Python and CLI tests plus a dedicated visual-default policy document
  • update agent instructions, the durable SPEC, audit-rule documentation, and changelog

Why

AI chart generators can introduce cropped axes or normalized/100%-stacked values as an aesthetic default even when the user never asked to change the frame of reference. The chart may remain technically valid while frustrating the user or changing the apparent magnitude and units of the result.

This PR makes the default contract simple: preserve the user's original scale and units unless the user explicitly requested a transformation.

The authorization metadata is only a deterministic declaration boundary; it does not prove the user actually made the request, and agents are explicitly instructed not to add it merely to obtain a passing audit.

Behavior

  • untouched quantitative scale -> policy PASS
  • cropped line/point scale without declaration -> BLOCK
  • cropped line/point scale with explicit user-request declaration -> policy PASS
  • stack: "normalize" without declaration -> BLOCK
  • normalization with explicit user-request declaration -> policy PASS
  • truncated quantitative bar -> still BLOCK, including explicit numeric domains that exclude zero

Validation

Local execution was unavailable because the container could not resolve GitHub. CI is the executable gate for this draft PR.

Focused coverage is in:

  • tests/test_spec_policy.py
  • tests/test_cli_visual_defaults.py

No new runtime dependency or chart intent is introduced.

@tmusser
tmusser marked this pull request as ready for review August 16, 2026 23:38
@tmusser
tmusser merged commit 494f0a0 into main Aug 16, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant