chart-contract: Instructions file for Codex

AGENTS.md

• Preserve the v0.1 scope in artifacts/SPEC.md.
• Do not add UI, dashboards, or extra chart types without updating artifacts/SPEC.md.
• Keep process_tree a rooted, acyclic structural intent; do not silently broaden it into a general graph, DAG, swimlane, or cyclic flowchart engine.
• Treat process-tree geometry as schematic: only parent-child topology, direction, labels, and optional branch text are authoritative.
• Prefer deterministic audit rules over vague judgment.
• Keep warnings explainable.
• Do not claim causality unless evidence supports it.
• Preserve the exact analytical claim in first-party rendered specs as usermeta.claim, independent of display title.
• If an audited spec carries usermeta.claim, do not silently substitute a different out-of-band claim; an exact mismatch must remain a deterministic failure.
• Treat a matching embedded claim as identity/provenance only, not evidence that the claim is true or supported.
• Do not mutate or fetch external data.
• Do not silently truncate quantitative scales or normalize values. For external Vega-Lite specs, require explicit usermeta.user_requested_scale_override=true or usermeta.user_requested_normalization=true before those transformations can pass the policy audit.
• Treat user-request metadata as a declaration, not proof that the user actually requested the transformation.
• A truncated quantitative bar baseline remains a visual-integrity failure even when user-request metadata is present.
• Never infer percent representation from observed value ranges. When percent presentation is explicit, require value_representation to distinguish fractional values from percentage-point values.
• Do not rescale percent data to obtain a passing audit. Preserve raw values and use display formatting that matches the declared representation.
• Do not treat a generic rate unit as percent; rates may use unrelated denominators or scales.
• Do not infer metric identity or definition stability from a column name, title, unit, claim, or source string; metric-definition metadata is explicit and opt-in.
• When a metric basis field is declared, mixed or mismatched metric versions block rather than being treated as comparable observations.
• Treat matching metric-definition metadata as identity consistency only, not proof that upstream computation implemented the declared business definition.
• Do not assume a stable metric field/definition implies a stable filtered or cohort universe; analysis-scope identity is explicit and opt-in.
• When a scope basis field/value is declared, mixed or mismatched row-level scope identities block rather than being treated as comparable evidence.
• Treat matching analysis-scope metadata as identity consistency only, not proof that upstream SQL, cohort membership, or filter predicates implemented the declared scope.
• Do not infer source measurement units from displayed labels, field names, geography, or value ranges; source/display unit identity is explicit metadata.
• Never equate unavailable values with observed zero. Declared missing/suppressed rows must carry null metrics; structural-zero rows must contain numeric zero. Preserve source row states and fail on contradictions.
• Recompute observation-state counts from the full evidence, not from the rendered subset; do not invent missingness mechanisms or claim visual gap presentation is proven by metadata.
• Never silently convert values to make a unit contract pass. Fixed-scale conversions must preserve original source values and reproduce the declared factor against supplied evidence.
• Treat matching fixed conversion arithmetic as a reproducible receipt only, not validation of FX provenance, inflation methodology, time-varying rates, or offset conversions.
• Do not equate chart row count with sample size; aggregated evidence can summarize many sampled units. Only reconstruct sample size when an explicit sample-member field is supplied.
• Treat population and sampling metadata as scope/provenance, not proof of representativeness, random selection, nonresponse validity, or unbiased population inference.
• Population generalization is explicit metadata in v1. Convenience/quota/unknown/other sampling plus declared generalization requires review. Missing population metadata may also REVIEW only for the bounded explicit phrases sample of, sampled from, survey respondent(s), or census of; do not broaden this into arbitrary population-language NLP.
• Sampling weights must be inspectable positive finite values when declared, but passing weight checks do not certify calibration, design effects, or variance estimation.
• Treat error bars as explicit semantic contracts, not generic uncertainty decoration: preserve estimate/lower/upper fields, interval kind, level, and method together.
• Require uncertainty bounds to be complete, finite, numeric, and contain the estimate; do not repair or reorder malformed intervals automatically.
• When interval metadata is declared, the visible spec must actually bind the declared lower/upper fields; metadata-only uncertainty is not enough.
• Do not infer statistical significance, hypothesis-test conclusions, calibration, or coverage from interval overlap/non-overlap or a passing interval contract.
• Treat control-total reconciliation as arithmetic over supplied component evidence, not proof that the component taxonomy is conceptually complete or that the declared control source is authoritative.
• Do not silently synthesize Unknown/Other/balancing components to force reconciliation. Surface the residual and require upstream resolution.
• Fixed v1 reconciliation uses sum semantics only; do not reconcile percent/rate/ratio values by summing them.
• Reconciliation does not replace rank/top-N omission rules: full supplied evidence may reconcile while a truncated display still requires explicit comparison-set treatment.
• Do not infer numerator, denominator, or cohort identity for ratio-like metrics from field names, claim text, or observed values; missing semantics may require review, while contradictory declared semantics block.
• Treat a declared denominator basis field as semantic identity, not denominator magnitude: different row counts are allowed, but mixed identities such as visitors and signups under one metric must not pass.
• Do not describe a matching ratio contract as proof that numerator/denominator arithmetic or cohort membership is correct upstream.
• Do not collapse absolute delta, percentage-point change, percent change, and ratio into one generic “change” semantic; preserve the declared arithmetic mode.
• A comparison baseline must resolve to explicit supplied observations; do not infer a hidden baseline from row order, chart position, or prose alone.
• Treat stored comparison metric values and computed change as reproducible receipts, not proof that the chosen baseline is analytically appropriate.
• Do not equate an increase with improvement or a decrease with deterioration. When evaluative wording matters, require explicit metric directionality plus an explicit comparison baseline.
• Keep directionality parsing deliberately narrow: better/improved versus worse/worsened/deteriorated. Descriptive increase/decrease wording is not an evaluative judgment.
• Treat neutral directionality as a declaration that chart-contract should not label movement as better or worse; evaluative claims against neutral metrics block.
• Do not infer a business target from metric directionality, the latest row, chart position, title text, or a target-looking value; target semantics are explicit and separately contracted.
• Target contracts select exactly one supplied observation and use only at_least, at_most, or equal with optional absolute tolerance; do not silently choose a reporting point.
• When target metadata is declared, preserve a visible threshold rule and durable observed-value/gap/status receipts; do not keep metadata after the line or evidence changes.
• Treat met/missed-target claim parity as semantic consistency only, not proof that the target is authoritative, material, achievable, or statistically meaningful.
• Treat source grain as row identity: declared grain fields must be non-null and unique; do not silently deduplicate duplicate grain keys.
• Do not collapse a finer source grain into a coarser displayed grain without an explicit aggregation operation; never guess sum versus mean versus another reducer.
• Treat matching grain/aggregation receipts as structural consistency only, not proof that the declared business key or aggregation is substantively correct.
• Do not infer full-period, month-to-date, or rolling-window semantics from labels alone; temporal baseline comparisons should declare exact window boundaries.
• Never auto-prorate or normalize unequal comparison windows to make them pass. Unequal rolling durations block; complete calendar periods with different day counts require review.
• Treat completeness flags as declared period state, not proof that upstream ingestion is actually complete.
• Parse claim wording only for narrow explicit numeric percent/percentage-point/ratio phrases; do not expand this into open-ended NLP adjudication.
• Treat explicit Vega-Lite analytical transforms as part of the audited contract. Inventory their kind and exact location and require usermeta.transform_contract.declared to exactly match the detected transform-kind set.
• A matching transform declaration is visibility/provenance only. Do not translate it into approval, user consent, analytical correctness, or evidence that chart-contract executed the transform.
• Do not evaluate arbitrary Vega-Lite expressions merely to make a transformed spec pass; preserve the boundary between structural transform auditing and data reconstruction.
• Require occurrence-level transform lineage receipts for auditable transforms. Receipts may hash exact structural payloads and expose bounded field lineage, but must never be described as execution proof or upstream provenance attestation.
• Regenerate lineage receipts only from the final spec structure; do not hand-edit receipt hashes to make stale metadata pass.
• Treat usable-row coverage as a visibility contract over fields required by the chart/spec. Do not describe a high coverage percentage as proof of representativeness or random missingness.
• Treat materially uneven group coverage as a human-review signal, not evidence that missingness caused the observed group difference.
• Do not invent coverage for transform-derived fields that cannot be deterministically reconstructed from the supplied evidence.
• Rank charts require one explicit row per category; do not silently aggregate duplicate categories to make a ranking pass.
• Top-N rank truncation must be explicit, preserve full source evidence in first-party specs, declare omitted-category counts, and include all exact metric ties at the cutoff rather than applying an arbitrary hidden tie-break.
• Deterministic category ordering inside equal metric values is display stabilization only; do not describe it as distinct analytical rank.
• Truncated rank charts must make omitted-category treatment explicit: exclusion and aggregation into Other are different analytical contracts.
• Treat omitted metric mass as a completeness receipt, not proof of category importance; excluding at least half of non-negative metric mass requires human review.
• An aggregate Other bucket is a summary bucket, not another analytical rank. Pin it after ranked categories and never sum percent/rate/ratio metrics into Other.
• Treat the machine-readable audit profile as descriptive ruleset metadata, not another audit or scientific approval artifact.
• Do not recompute a report binding to legitimize post-audit edits to findings or verdict fields; rerun the audit and emit a new report.
• Treat a saved-report audit-profile mismatch as stale policy identity that requires re-audit for current verification, not as proof that either policy is better or scientifically valid.
• Do not translate a matching audit-profile digest or a profile diff into a claim that a chart is safe, valid, compatible, improved, or scientifically sound.
• Keep package/tool metadata separate from semantic audit-profile identity so version-only drift does not masquerade as policy drift.
• Update artifacts/VERIFY.md after changes.
• Update artifacts/HANDOFF.md before ending a session.