Make research findings citable

The brief at agentctx.go:167 advertised findings[].id and findings[].confidence
to every research session. The struct carried neither, so encoding/json dropped
both on every seal, silently, for as long as the schema has existed. A plan
phase had nothing stable to cite and no way to tell an observation from an
assumption.

Finding gains ID and Confidence. Ids are unique within an artifact and shaped
so "research:<id>" is unambiguous in plan prose. Confidence is fact, inference,
or assumption, matching the labels the output style already uses.

DecodeStoredResearch reads what is already in the CAS and backfills both.
Refusing an artifact sealed before this change would block every task whose
research predates it, including at rotation, where the agent that could fix it
is already gone. A backfilled finding is labelled inference rather than fact:
the old schema required evidence and made no verification claim, so upgrading
it on the way in would be the same class of lie this commit removes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CVbaKucEYBjMqVeUgJUsc1
This commit is contained in:
2026-08-28 11:21:29 +04:00
parent 4e244d8104
commit 822f086451
9 changed files with 133 additions and 13 deletions
+46 -2
View File
@@ -7,7 +7,7 @@ import (
func research() Research {
return Research{
Findings: []Finding{{Claim: "attribution runs per figure", Evidence: "internal/attr/attr.go:88"}},
Findings: []Finding{{ID: "r1", Confidence: Fact, Claim: "attribution runs per figure", Evidence: "internal/attr/attr.go:88"}},
Code: []CodePath{{Path: "internal/attr/attr.go", Why: "aggregation happens here"}},
Invariants: []string{"identity semantics must not change"},
DeadEnds: []DeadEnd{{Tried: "figure plurality", WhyFailed: "no measured gain"}},
@@ -59,7 +59,7 @@ func TestBoundsRejectUnboundedArtifacts(t *testing.T) {
"too many findings": func() error {
r := Research{}
for i := 0; i < 65; i++ {
r.Findings = append(r.Findings, Finding{Claim: "c", Evidence: "e"})
r.Findings = append(r.Findings, Finding{ID: "r1", Confidence: Fact, Claim: "c", Evidence: "e"})
}
return r.Validate()
},
@@ -99,3 +99,47 @@ func TestEncodeRejectsInvalid(t *testing.T) {
t.Fatal("Decode must reject non-JSON")
}
}
// The advertised schema promised findings[].id and findings[].confidence while
// the struct carried neither, so both were dropped silently on every seal. A
// plan cannot cite what was never stored.
func TestFindingIdentityIsRequiredAndUnique(t *testing.T) {
cases := map[string]Research{
"no id": {Findings: []Finding{{Confidence: Fact, Claim: "c", Evidence: "e"}}},
"upper case id": {Findings: []Finding{{ID: "R1", Confidence: Fact, Claim: "c", Evidence: "e"}}},
"spaced id": {Findings: []Finding{{ID: "r 1", Confidence: Fact, Claim: "c", Evidence: "e"}}},
"no confidence": {Findings: []Finding{{ID: "r1", Claim: "c", Evidence: "e"}}},
"bad confidence": {Findings: []Finding{{ID: "r1", Confidence: "certain", Claim: "c", Evidence: "e"}}},
"duplicate id": {Findings: []Finding{
{ID: "r1", Confidence: Fact, Claim: "c", Evidence: "e"},
{ID: "r1", Confidence: Inference, Claim: "d", Evidence: "f"},
}},
}
for name, r := range cases {
if err := r.Validate(); err == nil {
t.Errorf("%s: accepted, want a refusal", name)
}
}
}
// Research sealed before ids existed must stay readable. Refusing it would
// block every task whose research predates the change, including at rotation,
// where the agent that could fix it is already gone.
func TestStoredResearchWithoutIdentityStillDecodes(t *testing.T) {
legacy := []byte(`{"findings":[{"claim":"c","evidence":"e"},{"claim":"d","evidence":"f"}]}`)
if _, err := DecodeResearch(legacy); err == nil {
t.Fatal("a new seal without ids must be refused")
}
r, err := DecodeStoredResearch(legacy)
if err != nil {
t.Fatalf("stored decode: %v", err)
}
if r.Findings[0].ID != "legacy-1" || r.Findings[1].ID != "legacy-2" {
t.Fatalf("backfilled ids are not stable: %+v", r.Findings)
}
// Inference, not fact: the old schema required evidence and made no
// verification claim, so calling it fact would upgrade it on the way in.
if r.Findings[0].Confidence != Inference {
t.Fatalf("backfilled confidence is %q, want inference", r.Findings[0].Confidence)
}
}