docs(dev): clarify how to review duplicate ownership

This commit is contained in:
morluto committed 2026-11-21 15:12:26 -05:00
1 parent d777c3c55f
commit fb691dc98b
3 files changed
+25 -5

No files matched your search

+2
View File
@@ -37,6 +37,8 @@ Use "none" or "not applicable" only when established. -->
- Semantic owner and earliest changed stage:
<!-- Name the producer of parsed facts or resources and its affected consumers.
If ownership was duplicated, name the shared fact or responsibility and
show a case that distinguishes the old behavior from the corrected one.
Summarize superseded paths removed and any distinct policy, lifecycle,
lazy-loading, or compatibility responsibility retained. -->
- Contribution scope fit and linked maintainer decision:
+10 -5
View File
@@ -788,11 +788,16 @@ ownership or finalization changes; a single malformed fixture cannot establish
the whole contract.
When consolidating interpretation across consumers, use the same authored
input and an independently specified expected fact at the boundary where
each consumer previously made its own decision. Allow differences in
recovery or display when those belong to the consumer. For generated
installers and verifiers, exercise the emitted artifact in its supported
runtime so the test covers the code that actually receives the input.
input at the boundary where each consumer previously made its own decision.
Choose a case that makes competing interpretations disagree and a control
that should succeed. Assert the expected fact and its provenance independently
of the implementation. Allow differences in recovery or display when those
belong to the consumer. For generated installers and verifiers, exercise the
emitted artifact in its supported runtime.
When the operation changes state, verify the published or retained result as
well as preflight. When ownership includes cleanup, check who retains
responsibility after a failed attempt and what happens on retry.
When detection and detailed inspection share a reader, compare a valid
input, a recognizable malformed input, and a valid input whose examined
+13
View File
@@ -264,6 +264,19 @@ activation independently of readiness. An owned registration may be disabled
or stale; unresolved ownership remains unknown. Consumers use those facts
instead of reclassifying the raw command.
During review, name the fact or resource whose ownership must agree across
entry points. Trace where it is established, which consumers rely on it,
and where fallback, retry, or cleanup can change the outcome. Search for
other code that derives the same fact or claims the same responsibility.
Different implementations can still make the same decision independently.
Have the owner carry the result, its source and scope, and any uncertainty.
Each consumer applies its own policy to those shared facts. Keep proof of
identity and ownership separate from validity, readiness, and authority to
act. For an operation that needs fresh evidence, ask the same owner to
revalidate. For a proposed change, use the owner's rules to evaluate what
would remain before applying it.
Keep the reader's observation independent of the operation that needs it.
For example, the Evidence file reader can recognize the shape of an
analysis snapshot before authenticating it. Import and comparison can