# Operator warning truth and false-positive prevention Workpackage

Status: complete
Type: workpackage
Updated: 2026-07-26
Next Action: none; the Graph/export review and successor performance instrumentation are complete

Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md
Canonical Truth: docs/operator-warning-truth-policy.md
Incident: work/incidents/incident-controller-b-false-configuration-invalid-warning.md

## Current Context

Controller B displayed “Configuration is invalid or could not be saved” after
an ordinary setpoint change. A read-only capture taken before acknowledgement
proved the live and both persisted configurations were byte-identical,
CRC-valid, semantically valid, operational, and at generation 165. The commit
diagnostic showed attempt 2 succeeded, which exposes the HMI race: the first
failed attempt temporarily made configuration non-operational and the Home
screen latched that intermediate state before the automatic retry recovered.

The HMI contains about one hundred `newMsgNavScreen()` call sites. Most are
synchronous input feedback, explicit confirmations, status dashboards, or
terminal progress results. The highest false-positive risk is concentrated in
Home-screen asynchronous SD/configuration warnings and progress paths that
read mutable cross-thread state.

Controller B retains an intentionally abnormal three-lane HPT layout. It must
be programmed first and must not be formatted, initialized, replaced, or
removed while powered.

## Recommendation

Publish terminal, reason-specific subsystem snapshots; make retries silent;
revalidate the same snapshot immediately before display; key acknowledgement
to a fault transaction/episode; and retain first-failure evidence even when a
retry recovers.

Do not weaken semantic validation, persistence verification, or heating
interlocks merely to suppress warnings. Do not display a combined `A or B`
claim, infer physical SD absence, or claim a consequence that is no longer
true.

## Current State

Completed:

- Controller B pre-acknowledgement evidence captured, including CID, SD/HPT
  status, semantic/config commit status, RAM config, and both VEEPROM blocks.
- Every current message surface classified by evidence and operator-risk class.
- Canonical warning-truth policy defined and enforced by a 17-invariant gate.
- Configuration saves publish a bounded terminal transaction, preserve the
  first failure, remain operational during retries, and inhibit only after
  terminal invalidity or exhausted storage.
- Configuration, SD/HPT, and export warning paths use reason-specific owner
  state and immediate final revalidation.
- All 19 repository checks and the isolated clean Debug build passed.
- Exact candidate loaded on B first without formatting and then A.
- Both targets reproduced first-attempt `SSP_ERR_CMD_LOCKED`, recovered on
  attempt 2 without a warning, and restored exact original setpoint bits with
  identical RAM/VEEPROM mirrors.
- B retained its asymmetric lanes. A and B graph caches are complete with
  measured total times of `2.51 s` and `2.60 s`, respectively.

## Goal

Every product-generated warning is either based on immutable submitted input
or on a current terminal owner snapshot. Recovered retries remain silent,
real terminal failures remain visible and specific, diagnostics preserve the
cause, and both controls return to graph/operator review on one exact image.

## Why It Matters

False alarms teach operators to distrust real alarms. In this product they can
also falsely claim heating is disabled, creating avoidable process risk and
service intervention. The remedy must improve truth without masking actual
configuration, storage, SD, HPT, USB, or export failures.

## Major Outcomes

- Bounded configuration persistence transaction with retained diagnostics.
- Reason-specific, terminal configuration and SD warnings.
- Final pre-display revalidation and fault-epoch acknowledgement.
- Executable warning inventory enforcement and positive/recovery tests.
- B-first/A-second target evidence tied to image hash and SD CID.

## Delivery Stages

Use stages when sequencing, parity gates, or handoff cost matter.

| Stage | Outcome | Entry Evidence | Exit Evidence |
| --- | --- | --- | --- |
| 1 | Inventory and policy | B incident evidence | Canonical policy and classified call-site inventory |
| 2 | Configuration transaction | Existing retry loop | Terminal state, reason, attempts, first/final diagnostics |
| 3 | HMI migration | Owner snapshots | Final-rechecked, reason-specific config/SD/export warnings |
| 4 | Software gate | Source complete | Static/model/race tests and clean Debug build |
| 5 | Controller B proof | Exact hash and CID | Ordinary save recovers silently; positive states remain diagnosable; graph/cache ready without format |
| 6 | Controller A proof | B passes | Same image passes normal-media regression |
| 7 | Operator handoff | Electronic gates pass | Both controls ready at graph/cache review with evidence |

## Related Artifacts

- Incident:
  `work/incidents/incident-controller-b-false-configuration-invalid-warning.md`
- Runbook:
  `work/runbooks/runbook-autonomous-hpt-sd-qualification.md`
- Inventory:
  `work/inventories/inventory-smi-operator-warning-surfaces.md`
- Related performance work:
  `work/wp/completed/wp-optimize-hpt-triple-mirror-read-performance.md`

## Rough Sequence

1. Freeze the incident facts and classify warning surfaces.
2. Add the configuration persistence transaction and retained diagnostics.
3. Gate configuration and SD Home warnings on terminal, revalidated reasons.
4. Enforce the policy with static and race/recovery tests.
5. Build/package/hash, then program B without media changes.
6. Prove normal setpoint save, positive diagnostic states, graph readiness, and
   cache timing on B, then repeat the non-destructive regression on A.
7. Finish evidence and leave both controls ready for operator review.

## Milestones

### Milestone 1: Warning truth is enforceable

Completion criteria:

- [x] Every current warning surface is classified.
- [x] The evidence required for each class is documented.
- [x] High-risk asynchronous paths use terminal owner snapshots and revalidation.

### Milestone 2: Configuration race is eliminated

- [x] Retries are non-terminal and produce no modal.
- [x] Success after retry records first failure and recovery.
- [x] Exhausted storage and semantic invalidity produce distinct true warnings.
- [x] Heating-disabled wording is gated by the effective interlock.

### Milestone 3: Exact candidate is target-proven

- [x] All warning checks and clean build pass.
- [x] B retains CID and abnormal lanes; no format/reinitialization occurs.
- [x] A and B ordinary setpoint saves complete without false warning.
- [x] Both graph caches complete with recorded time and are ready for review.

## Open Questions

- Positive injected storage/semantic failures are destructive or safety
  relevant and require the existing controlled fault authorization before
  physical target execution. Software/model coverage is mandatory now;
  target fault injection remains separately governed.

## Completion Standard

This workpackage is complete when one exact image passes policy enforcement,
software/build gates, B-first and A-second non-destructive target validation,
preserves B media, records CID-linked evidence, and leaves both controls ready
for operator graph/cache review. Any authorized positive physical fault tests
not run now remain explicit release gates rather than implied passes.

## Closeout Routing

- Current truth promoted to: `docs/operator-warning-truth-policy.md`
- Historical context remains in:
  `work/incidents/incident-controller-b-false-configuration-invalid-warning.md`
- Runtime/status evidence:
  `work/evidence/hpt-log-store-circular-mirror/controller-b/`
- Closeout evidence:
  `work/evidence/operator-warning-truth-and-target-proof-20260726.md`
- Cleanup deferred to: none for current high-risk warnings; future warnings
  must follow the canonical policy
