ADR 0004: Assertion kinds and origin on every finding, hypothesis and proposed step

Status: Accepted
Date: 2026-09-13
Deciders: Founder, product team

Context

The brief requires that each proposed conclusion link back to its supporting evidence and clearly distinguish observed results from interpretations, assumptions and suggestions produced by the agents, and the brand voice guide says “Distinguish observed results from interpretations, assumptions, hypotheses, and proposed actions” and “Avoid styling an AI interpretation as a verified scientific finding”. The attribution word list (shared/attribution-words.json) rejects the label “AI” joined to “generated” in copy and publish scopes.

Decision

Findings, hypotheses, gaps, protocol and report drafts, and review findings carry assertion_kind in observation | interpretation | assumption | suggestion (text + named CHECK) where the record is a statement, and every agent-capable record carries origin in human | agent, a nullable agent_run_id, and illustrative (boolean).
Findings carry source_ids[]; hypotheses carry supporting_finding_ids[] and contradicting_finding_ids[]; review findings carry source_ref and requirement_code. A statement without a source is allowed only as an assumption or suggestion.
The UI renders an assertion chip that always prints the kind and the origin label (“Recorded by a person” or “Agent-generated, for review”); agent-origin records never use the success tone until a person accepts them.
Copy says “agent-generated” or “proposed”, never the rejected label.
Agent runs never change an approved record; they create new records in proposed, draft or open states for a person to decide.

Consequences

The API schemas, the web DTO mirror, the docs statuses page and the deck’s assertion-model diagram share the same four kinds and two origins.
Seeded records are labelled illustrative everywhere they appear.
Hypothesis decisions (accepted | rejected) and review decisions (accepted | dismissed | resolved) are recorded with a rationale and an audit row.

Alternatives considered

A free-text “confidence” field only: does not separate observation from interpretation; rejected.
A boolean is_agent: loses the four kinds; rejected.

Follow-ups

none