diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a8f6e166bf..681816f8a5 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -37,6 +37,8 @@ Use "none" or "not applicable" only when established. --> - Semantic owner and earliest changed stage: - Contribution scope fit and linked maintainer decision: diff --git a/docs/development/testing.md b/docs/development/testing.md index 0f6a754be6..061c0c7889 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -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 diff --git a/docs/development/tool-design.md b/docs/development/tool-design.md index 60b95db3eb..1154696614 100644 --- a/docs/development/tool-design.md +++ b/docs/development/tool-design.md @@ -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