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
+7 -4
View File
@@ -400,7 +400,7 @@ func (w *worker) start(ctx context.Context, t domain.Task, ref string) error {
if artErr != nil {
return fmt.Errorf("research artifact: %w", artErr)
}
r, decErr := workphase.DecodeResearch(b)
r, decErr := workphase.DecodeStoredResearch(b)
if decErr != nil {
return fmt.Errorf("research artifact: %w", decErr)
}
@@ -411,7 +411,7 @@ func (w *worker) start(ctx context.Context, t domain.Task, ref string) error {
if artErr != nil {
return fmt.Errorf("plan artifact: %w", artErr)
}
pl, decErr := workphase.DecodePlan(b)
pl, decErr := workphase.DecodeStoredPlan(b)
if decErr != nil {
return fmt.Errorf("plan artifact: %w", decErr)
}
@@ -1839,7 +1839,7 @@ type phaseRequest struct {
// be left. Phases absent from this table seal nothing.
var phaseArtifact = map[domain.WorkPhase]string{
domain.WorkPhaseResearch: "research.json",
domain.WorkPhasePlan: "plan.json",
domain.WorkPhasePlan: "plan.md",
}
func currentPhase(t domain.Task) domain.WorkPhase {
@@ -1946,7 +1946,10 @@ func (w *worker) requestPhase(ctx context.Context, id string, s herdr.Session) b
case domain.WorkPhaseResearch:
_, decErr = workphase.DecodeResearch(artifact)
case domain.WorkPhasePlan:
_, decErr = workphase.DecodePlan(artifact)
// A new seal is markdown. The coordinator re-parses and also
// resolves research citations, which the worker cannot check
// because it does not hold the accepted research.
_, decErr = workphase.ParsePlan(artifact)
}
if decErr != nil {
w.recordError(fmt.Errorf("phase request %s: %s artifact: %w", id, req.From, decErr))