# ADR-0016: AgFields Applied-Residue `hmax` Floor

Status: Accepted
Date: 2026-07-10

## Context

The `sacral-self-discipline` AgFields acceptance run uses ten managements
generated by Jim's plant-management interface. Every source contains an applied
residue plant named `L179_weed` whose `hmax`, `cuthgt`, `rdmax`, and `xmxlai` are
zero. Once rotation scenario overflow was fixed, `wepp_260430_hill` rejected the
referenced residue plant with `HMAX <= 0.0` before simulation.

The plant is referenced by residue-addition operations (`pcode` 10) but is not
used as an active crop or initial-condition plant. WEPP nevertheless validates
all referenced plant definitions. The maintainer identified this as systematic
interface output and authorized normalization during AgFields ZIP ingestion.

## Decision

During AgFields plant ZIP ingestion, set `hmax` to `0.00001 m` when all of the
following are true:

- the parsed value is nonpositive;
- the plant is referenced by a cropland residue-addition operation (`pcode` 10
  or 12); and
- the plant is not referenced as a yearly active plant or an initial-condition
  plant.

Apply the rule to both 2017.1 inputs before downgrade and raw 98.4 inputs before
final installation. Preserve original 2017.1 files unchanged and record the
normalization in additive inventory provenance. Do not normalize by scenario
name and do not change any other plant or operation parameter.

## Decision Provenance

Decision Venue: Codex API conversation, 2026-07-10 13:06 PDT
Participants Present: Roger Lew, Codex
Decision Owner(s): Roger Lew, WEPPpy maintainer
Implementer(s): Codex

## Change Summary

Old behavior: Jim-interface residue-only plants with `hmax=0` were accepted as
parse-valid and installed unchanged; WEPP later rejected them.

New behavior: qualifying residue-only plants are installed with
`hmax=0.00001 m`. `0.00001` is the smallest positive value preserved by the
five-decimal management serializer. The original source value and applied floor
are retained in provenance.

## Rationale

The floor satisfies WEPP's strict positive-input contract while adding the
smallest representable artificial height. Restricting the rule to residue-only
references ensures the fallback does not parameterize a growing crop. Semantic
reference analysis is more robust than coupling behavior to Jim's current
`L179_weed` name.

## Alternatives Considered

1. Reject the archive and require re-export - rejected because the zero-height
   placeholder is systematic interface output and the maintainer requested
   compatible ingestion.
2. Use `0.01 m` or copy the active crop height - rejected as larger and less
   neutral arbitrary parameterizations.
3. Normalize every nonpositive plant height - rejected because it could hide an
   invalid active-crop definition.
4. Patch WEPP validation - rejected because this is an input compatibility
   defect and weakening global validation would affect unrelated workflows.

## Consequences

Newly ingested final management files differ from their source for one narrowly
qualified field. Existing projects are unchanged until reprocessing. The
fallback clears the observed `HMAX <= 0` validation error, but it does not claim
the entire management is valid; current replay subsequently reaches an
independent zero-random-roughness SIGFPE in `frcfac`, which remains outside this
decision.

## Evidence

- `docs/work-packages/20260710_management_rotation_synth_hardening/`
- Run `/wc1/runs/sa/sacral-self-discipline`, sub-field 3733.
- All ten preserved 2017.1 source managements contain the same zero-height
  residue placeholder.
- Real-binary probes show both `0.00001 m` and `0.01 m` clear the `hmax`
  validation; the smaller serialized value is selected.

## Risk and Rollback Notes

Risk is bounded by residue-only reference gating and explicit provenance. Roll
back if the interface begins using these scenarios as active crops, if WEPP uses
`hmax` in residue-addition calculations, or if comparison runs show a material
output effect. Revert the helper and restore final files from preserved 2017.1
sources; additive provenance needs no migration.

## Implementation Notes

Regression coverage must exercise both input formats, prove active plants are
untouched, and replay the exact p3733 schedule. Do not normalize the separate
zero random-roughness operation exposed after this floor.
