docs(227): ADR on input-validation checking semantic shape, not just type (#228)

* docs(227): create ADR for input-validation-shape-not-just-type

Captures the architectural standard that defensive normalization at trust
boundaries must validate both type and semantic shape, with silent
coercion on failure. Concrete cases: parentTraceId UUID v4 fix in
PR #225 and release-version validation in ADR 218.

Closes #227

* docs(227): cross-reference new ADR from ADR 218

Appends a "See also" section at the end of ADR 218 pointing forward to
ADR 227, which generalises the type+semantic-shape validation principle
documented in ADR 218's narrower release-workflow context.

* docs(227): add CONTRIBUTING pointer to new ADR

Adds a "Code Review Lessons → Input validation" section after the
Reviewer Standards block, linking to ADR 227 as the citable reference
for the type+semantic-shape validation standard.
This commit is contained in:
Tom Boucher
2026-05-24 16:32:01 -04:00
committed by GitHub
parent 2d14eb8873
commit 7c539cb86a
3 changed files with 120 additions and 0 deletions

View File

@@ -758,6 +758,12 @@ Reviewers do not rely solely on CI to verify correctness. Before approving a PR,
**"Tests pass in CI" is not sufficient for merge.** The implementation must correctly solve the problem described in the linked issue.
## Code Review Lessons
### Input validation: check shape, not just type
Defensive normalization at trust boundaries must validate both the value's type and its semantic shape. A `typeof === 'string'` check is necessary but insufficient when the field's contract requires a specific format (UUID v4, semver, file path, etc.). See [ADR 227](docs/adr/227-input-validation-shape-not-just-type.md) for the architectural standard and concrete cases.
## Code Style
- **CommonJS** (`.cjs`) — the project uses `require()`, not ESM `import`