pbakaus_impeccable/docs/COMP-GATE-INTEGRITY.md

Comp gate evidence and integrity

Comp fidelity still has two independent requirements: the numeric score and the absence of blocking findings. A high overall score, a repeated attempt, or an existing plate file does not satisfy a missing-region check.

Measurements and decisions

comp-diff measures the declared region bounds. It does not enlarge a narrow region to include neighbouring elements. Subpixel regions sample at least one real source pixel, including at image edges. Coverage and region-kind checks remain the responsibility of comp-spec; this change does not authorize omitting regions or shrinking their bounds to exclude required work.

A standalone comp-diff report contains raw verdicts. The hero gate can interpret those measurements using current plate validation and rendered presence. For hero and responsive evidence:

• raw-report.json retains uninterpreted metrics and verdicts.
• report.json retains the same scores, adds rawVerdict to each region, and publishes the effective verdict used by the gate and paired image label.
• gate.ok and gate.reasons describe whether advancement is allowed and all unresolved blockers. drift alone does not mean a region is nonblocking.
• Paired images label their gate status as BLOCKING, NONBLOCKING, or CHECK GATE, using the same report fields.
• Region-specific blockers are recorded as blockingReasons. blocking: null means an unscoped blocking finding prevents attributing a clean bill of health to that region. Unscoped findings remain in gate.unscopedReasons; they are not hidden or waived.

When capture, spec, or plate validation fails before measurement, the current report has measurementsAvailable: false, no region results, and the failed gate reasons. It does not present the preceding capture as current evidence.

Repair crops include only regions with current blockers; shared readings retain all affected region IDs. Frame-wide blockers keep their whole-frame evidence. Both hero and responsive reports are marked incomplete before preflight and image writes, then committed atomically only after the evidence files succeed. Each attempt clears the previous raw report, whole-frame PNGs, and region PNGs; failed attempts also clear any partial evidence they wrote. Removed regions cannot leave old crops in a successful comparison. Cleanup is limited to generated files, does not follow region-directory symlinks, and blocks the gate if it fails. When removal fails, the remaining generated set is renamed beside its current paths under a unique invalid-comparison-* prefix. artifactCleanup and a quarantine manifest record the moved paths. Keeping the same parent avoids requiring write access to the read-only directory itself. If filesystem permissions also prevent quarantine, that field records the error and explicitly lists the invalid artifact paths; no evidence is certified and the gate remains closed. Write failures block the gate and, when the report location is writable, publish an unavailable-evidence report.

Stall feedback follows repeated blocking reasons. It never chooses an asset to regenerate solely because that asset has the lowest raw score. The feedback is additional context; it does not clear a finding or advance the phase.

Plate validation

Successful plate receipts include SHA-256 fingerprints of the asset bytes, measured region, and comp. Hero and responsive gates revalidate receipts. A changed or deleted file, a changed region, or a changed comp invalidates the receipt. Legacy score-only receipts are revalidated. An invalid plate cannot receive an ok receipt merely because its PNG decoded. Rendered presence is still checked after asset validation, so a file hidden in the page does not count as placed.

Overrides

A --force --reason must contain a direct quoted downgrade of comp authority immediately attributed to the user. An unrelated mention of the user does not authorize a quote from another speaker. Generic delegation, the builder's surrounding claim that it may proceed, or a gate exception does not establish that authorization. The quote parser is deliberately conservative. It cannot authenticate a quote: the calling harness must retain the actual user answer and assess provenance. Neither local receipts nor caller-written state are a security boundary against an agent with arbitrary write access to all files and engine code.

Validation

The comp-verbs regressions cover narrow-region isolation, changed/deleted plate receipts, comp-crop reuse, hidden rendered assets, repeated failed attempts, ambiguous overrides, spec coverage and kind refusals, and raw/effective report agreement. They do not certify semantic equivalence of arbitrary artwork or justify relaxing a fidelity threshold.