Seal the plan as a specification instead of four bullet lists

The plan artifact was Changes{Target,Intent} plus three string lists, every
entry capped at 500 single-line characters. That bound makes a specification
impossible: a phase cannot carry a code block, a paragraph of reasoning, or a
verification command with its own argument list. renderSealed then flattened
what little survived through collapse(), so an implement session received a
summary of a summary.

plan.md replaces it. Markdown, 128 KiB, no per-line cap, sealed through the
existing path under the existing PlanRef. The parser enforces the structure the
brief states: required sections, phases numbered from 1 with no gaps, Files,
Changes and Verification per phase, and at least one automated or manual check,
because a phase nobody can verify can never be established as done. Automated
entries are JSON argv arrays, so a pipe is a literal argument rather than an
operator. Headings inside fenced blocks are content, so a plan may show
markdown without parsing its own example.

Citations resolve at seal time against the accepted research, on the
coordinator, which is the only party holding ResearchRef. A plan resting on a
finding nobody recorded fails on the planner while its session is still alive
to be told.

The plan now renders byte for byte into the implement launch, and a rotated
successor receives the same complete document. That is the property the whole
change exists for. collapse() stays for research findings, which really are
short claims.

DecodeStoredPlan reads pre-markdown refs and renders them into the same type,
labelled, so nothing downstream branches on which era a plan came from. A
legacy plan carries no phases, which is honest: the old artifact never named an
executable unit.

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:36:45 +04:00
parent 822f086451
commit 57c028f94f
22 changed files with 1070 additions and 145 deletions
+53 -11
View File
@@ -176,7 +176,7 @@ func buildFor(t *testing.T, s *store.Store, task domain.Task) string {
if err != nil {
t.Fatal(err)
}
p, err := workphase.DecodePlan(b)
p, err := workphase.DecodeStoredPlan(b)
if err != nil {
t.Fatal(err)
}
@@ -241,16 +241,58 @@ func sealedResearch(t *testing.T) []byte {
func sealedPlan(t *testing.T) []byte {
t.Helper()
b, err := workphase.Encode(workphase.Plan{
Changes: []workphase.Change{{Target: "internal/attr/attr.go", Intent: "add the cache"}},
Verification: []string{"go test ./internal/attr/"},
})
if err != nil {
t.Fatal(err)
b := []byte(planMarkdown)
if _, err := workphase.ParsePlan(b); err != nil {
t.Fatalf("the fixture plan does not satisfy the seal: %v", err)
}
return b
}
// planMarkdown is a real sealed specification, not a fixture shaped to pass.
// The assertions below read its content back out of the rendered context,
// which is what proves the plan survives a phase boundary intact.
const planMarkdown = "# Attribution cache implementation plan\n" + `
## Overview
Add the cache so attribution stops recomputing per figure.
## Current state
Attribution runs per figure, per research:r1.
## Desired end state
internal/attr/attr.go: add the cache, keyed per person.
## Non-goals
No change to identity semantics.
## Approach
Memoise inside the existing aggregation loop.
## Phase 1: Add the cache
### Files
- internal/attr/attr.go
### Changes
internal/attr/attr.go: add the cache, keyed per person.
### Verification
#### Automated
- run: ["go", "test", "./internal/attr/"]
## Testing strategy
The package test covers aggregation.
## Risks and edge cases
A stale entry would misattribute.
## Migration
None.
## References
- research:r1
`
func assertContains(t *testing.T, phase, ctx string, want ...string) {
t.Helper()
for _, w := range want {
@@ -334,7 +376,7 @@ func TestTrajectoryGateCorrectionOutranksTheSealedPlan(t *testing.T) {
"## Current human decisions",
"add the index instead",
"## Accepted plan",
"internal/attr/attr.go: add the cache",
"internal/attr/attr.go: add the cache, keyed per person.",
)
}
@@ -405,7 +447,7 @@ func TestBlockingQuestionResumesWithTheAnswerOnTop(t *testing.T) {
// The resumed context: the answer above the sealed plan, and the question
// gone because it is answered.
ctx := buildFor(t, s, resumed)
assertContains(t, "resumed", ctx, "break compatibility", "## Accepted plan", "internal/attr/attr.go: add the cache")
assertContains(t, "resumed", ctx, "break compatibility", "## Accepted plan", "internal/attr/attr.go: add the cache, keyed per person.")
if strings.Contains(ctx, "## Human decision required") {
t.Fatalf("an answered question is still being asked:\n%s", ctx)
}
@@ -414,7 +456,7 @@ func TestBlockingQuestionResumesWithTheAnswerOnTop(t *testing.T) {
"break compatibility",
"## Accepted research",
"## Accepted plan",
"internal/attr/attr.go: add the cache",
"internal/attr/attr.go: add the cache, keyed per person.",
)
}
@@ -488,7 +530,7 @@ func TestReviewSessionIsIndependent(t *testing.T) {
if err != nil {
t.Fatal(err)
}
sealedPlanValue, err := workphase.DecodePlan(planArtifact)
sealedPlanValue, err := workphase.DecodeStoredPlan(planArtifact)
if err != nil {
t.Fatal(err)
}