kami/orchestra
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Seal the plan as a specification instead of four bullet lists

Browse Source 
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:
kami
2026-08-28 11:36:45 +04:00
parent 822f086451
commit 57c028f94f
22 changed files with 1070 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/operations/phase_request_test.go
+1 -1
View File
@@ -51,7 +51,7 @@ func TestRequestWorkPhaseAdvancesAndSealsEachArtifact(t *testing.T) {
if _, err := RequestWorkPhase(s, project, id, epoch, "op-4", domain.WorkPhasePlan, domain.WorkPhaseImplement, nil); !errors.Is(err, domain.ErrInvalid) {
t.Fatalf("leaving plan unsealed must fail, got %v", err)
}
if _, err := RequestWorkPhase(s, project, id, epoch, "op-5", domain.WorkPhasePlan, domain.WorkPhaseImplement, sealed(t, plan)); err != nil {
if _, err := RequestWorkPhase(s, project, id, epoch, "op-5", domain.WorkPhasePlan, domain.WorkPhaseImplement, planDoc); err != nil {
t.Fatal(err)
}
got, _ = s.Task(id)
internal/operations/review_test.go
+1 -1
View File
@@ -34,7 +34,7 @@ func atImplement(t *testing.T, project registry.Project) (*store.Store, string)
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, research)); err != nil {
t.Fatal(err)
}
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, plan)); err != nil {
if _, err := AdvanceWorkPhase(s, project, id, planDoc); err != nil {
t.Fatal(err)
}
return s, id
internal/operations/trajectory.go
+9 -24
View File
@@ -122,30 +122,15 @@ func TrajectoryGatePacket(s *store.Store, t domain.Task, from, to domain.WorkPha
}
}
if len(planned) > 0 {
{
if p, err := workphase.DecodePlan(planned); err == nil {
b.WriteString("\nProposed changes:\n")
for _, c := range p.Changes {
fmt.Fprintf(&b, "- %s: %s\n", oneLine(c.Target), oneLine(c.Intent))
}
if len(p.Verification) > 0 {
b.WriteString("\nVerification:\n")
for _, v := range p.Verification {
fmt.Fprintf(&b, "- %s\n", oneLine(v))
}
}
if len(p.Risks) > 0 {
b.WriteString("\nRisks:\n")
for _, r := range p.Risks {
fmt.Fprintf(&b, "- %s\n", oneLine(r))
}
}
if len(p.DecisionsNeeded) > 0 {
b.WriteString("\nOpen decisions for you:\n")
for _, d := range p.DecisionsNeeded {
fmt.Fprintf(&b, "- %s\n", oneLine(d))
}
}
// The plan reaches the human as the document that was sealed. A
// trajectory gate asks whether this direction is right, and a
// flattened summary is not the thing being approved. maxPacketBytes
// below bounds what a notification surface actually carries.
if p, err := workphase.DecodeStoredPlan(planned); err == nil {
b.WriteString("\nProposed plan:\n\n")
b.WriteString(p.Markdown)
if !strings.HasSuffix(p.Markdown, "\n") {
b.WriteString("\n")
}
}
}
internal/operations/trajectory_test.go
+43 -8
View File
@@ -10,7 +10,6 @@ import (
"orchestra/internal/domain"
"orchestra/internal/registry"
"orchestra/internal/store"
"orchestra/internal/workphase"
)
func gatedProject() registry.Project {
@@ -55,11 +54,47 @@ func TestTrajectoryGateBlocksThenClears(t *testing.T) {
}
// plan to implement is gated.
proposal := sealed(t, workphase.Plan{
Changes: []workphase.Change{{Target: "internal/attr/attr.go", Intent: "add the cache"}},
Verification: []string{"go test ./internal/attr/"},
Risks: []string{"cache invalidation on rename"},
})
proposal := []byte("# Attribution cache plan\n" + `
## Overview
add the cache
## Current state
runs per figure, per research:r1.
## Desired end state
Aggregation is cached per person.
## Non-goals
No identity change.
## Approach
Memoise in the aggregation loop.
## Phase 1: Add the cache
### Files
- internal/attr/attr.go
### Changes
add the cache to internal/attr/attr.go
### Verification
#### Automated
- run: ["go", "test", "./internal/attr/"]
## Testing strategy
go test ./internal/attr/
## Risks and edge cases
cache invalidation on rename
## Migration
None.
## References
- research:r1
`)
_, err := AdvanceWorkPhase(s, project, id, proposal)
if !errors.Is(err, ErrTrajectoryGate) {
t.Fatalf("want ErrTrajectoryGate, got %v", err)
@@ -122,7 +157,7 @@ func TestUngatedProjectAdvances(t *testing.T) {
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, research)); err != nil {
t.Fatal(err)
}
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, plan)); err != nil {
if _, err := AdvanceWorkPhase(s, project, id, planDoc); err != nil {
t.Fatal(err)
}
if got, _ := s.Task(id); got.WorkPhase != domain.WorkPhaseImplement {
@@ -141,7 +176,7 @@ func TestOlderDecisionDoesNotOpenTheGate(t *testing.T) {
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, research)); err != nil {
t.Fatal(err)
}
if _, err := AdvanceWorkPhase(s, project, id, sealed(t, plan)); !errors.Is(err, ErrTrajectoryGate) {
if _, err := AdvanceWorkPhase(s, project, id, planDoc); !errors.Is(err, ErrTrajectoryGate) {
t.Fatalf("want ErrTrajectoryGate, got %v", err)
}
}
internal/operations/workphase.go
+35 -1
View File
@@ -4,6 +4,7 @@ import (
"encoding/json"
"errors"
"fmt"
"strings"
"orchestra/internal/authz"
"orchestra/internal/domain"
@@ -71,7 +72,16 @@ func advanceWorkPhase(s *store.Store, project registry.Project, taskID string, a
return domain.Event{}, err
}
case domain.WorkPhasePlan:
if _, err := workphase.DecodePlan(artifact); err != nil {
doc, err := workphase.ParsePlan(artifact)
if err != nil {
return domain.Event{}, err
}
// Citations resolve here and nowhere else: the coordinator holds
// ResearchRef, so this is the only party that can tell whether a
// cited finding exists. A plan resting on a finding nobody
// recorded fails on the planner, while its session is still alive
// to be told, rather than on the implementer later.
if err := resolvePlanReferences(s, t, doc); err != nil {
return domain.Event{}, err
}
}
@@ -169,3 +179,27 @@ func phaseOperation(s *store.Store, taskID, operationID string) (domain.Event, b
}
return domain.Event{}, false
}
// resolvePlanReferences refuses a plan that cites research the task never
// sealed. Its cost is one CAS read against a ref the coordinator already
// holds.
func resolvePlanReferences(s *store.Store, t domain.Task, doc workphase.PlanDoc) error {
if len(doc.References) == 0 {
return nil
}
if t.ResearchRef == "" {
return fmt.Errorf("%w: the plan cites %s but this task sealed no research", domain.ErrInvalid, strings.Join(doc.References, ", "))
}
raw, err := s.Artifact(t.ResearchRef)
if err != nil {
return fmt.Errorf("resolve plan references: %w", err)
}
r, err := workphase.DecodeStoredResearch(raw)
if err != nil {
return fmt.Errorf("resolve plan references: %w", err)
}
if missing := doc.ResolveReferences(r); len(missing) > 0 {
return fmt.Errorf("%w: the plan cites research:%s, which the accepted research does not contain", domain.ErrInvalid, strings.Join(missing, ", research:"))
}
return nil
}
internal/operations/workphase_test.go
+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)