My parser reported a parse error on a file that was never malformed

A build process encountered a parse error when attempting to extract requirement tables from a document, even though the document was perfectly structured and the parser was functioning correctly. The parser failed because it incorrectly treated the entire file as prose, not recognizing the absence of structured forms declared in the document.

This resulted in 256 well-formed rows being misidentified as paragraphs, leading to a parse failure. The issue was not with the document or the parser, but with the declaration that connected them. The more useful reason code would have been "this file declares zero structured forms," as it is detectable without needing to know the contents of the document.

The second issue discovered was a nondeterministic failure during regeneration of derived artifacts, caused by uncommitted changes in a file used as an input. The correct handling is to regenerate at a committed boundary and commit that state. This rule is sometimes overlooked because the output usually appears correct. The two runs that disagreed were the only reason the issue was identified, despite a single run over a dirty tree producing a plausible artifact and hash that would never reproduce.

The key takeaway is that when a reason code names a stage, it should be treated as a location, not a cause. Asking what the stage was before asking what it did is the better approach. Derived artifacts must be regenerated from a committed state, not a clean-enough tree or changes that exist only on one machine, as the point of a derived artifact is to allow someone else to rebuild it and get the same bytes.