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
+45 -2
View File
@@ -47,7 +47,50 @@ func sealed(t *testing.T, v interface{ Validate() error }) []byte {
}
var research = workphase.Research{Findings: []workphase.Finding{{ID: "r1", Confidence: workphase.Fact, Claim: "runs per figure", Evidence: "attr.go:88"}}}
var plan = workphase.Plan{Changes: []workphase.Change{{Target: "attr.go", Intent: "aggregate per person"}}}
// planDoc is a real sealed specification. It cites research:r1, which the
// research fixture above contains, so the reference check has something to
// resolve.
var planDoc = []byte("# Attribution plan\n" + `
## Overview
Aggregate per person.
## Current state
attr.go aggregates per figure, per research:r1.
## Desired end state
attr.go aggregates per person.
## Non-goals
No identity change.
## Approach
Change the aggregation key.
## Phase 1: Aggregate per person
### Files
- attr.go
### Changes
Change the aggregation key to the person.
### Verification
#### Automated
- run: ["go", "test", "./internal/attr/"]
## Testing strategy
Package test.
## Risks and edge cases
None known.
## Migration
None.
## References
- research:r1
`)
func TestFullPhasePathSealsEachArtifact(t *testing.T) {
s, id := phaseStore(t)
@@ -79,7 +122,7 @@ func TestFullPhasePathSealsEachArtifact(t *testing.T) {
// plan -> implement must seal the plan, and must not overwrite the
// research ref.
researchRef := got.ResearchRef
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, plan)); err != nil {
if _, err := AdvanceWorkPhase(s, project, id, planDoc); err != nil {
t.Fatal(err)
}
got, _ = s.Task(id)