a3f571d672
Every item wrote the shared, append-only docs (android/README.md, docs/cli.md and the packaged skill references), so every merge conflicted on prose. Keep the duty to notice stale docs; move the writing to one deliberate place. - Per-item note, not a shared edit. An item that makes a shared document stale writes docs/notes/<slug>.md - unique per item, so two items never touch the same file - and commits that note with its change. It never edits a README, topic doc or packaged skill reference itself. - One writer. The manual-only docs-fold pipeline, bundled as the fifth starter examples/docs-fold.md, folds every note under docs/notes/ into the shared document it names and deletes the consumed notes in its own commit; an empty notes directory is a success no-op. Operator trigger: pipelines new "Docs fold" --template docs-fold --no-open; pipelines submit <draft.md>; pipelines run "Docs fold". - Implemented where the convention lives: orchestration.md (brief item 5, the hard-constraint bullet, a "Single documentation writer" section and the "Pipeline choice" committer bullet), the canonical committer checklist in format.md (new step 6), the committer prompts in examples/task.md and examples/three-stage.md, the new examples/docs-fold.md with its catalog and README entries, and the repository guideline AGENTS.md. Test-expectation counts (examples/catalog_test.go, internal/server/templates_test.go, scripts/smoke-first-install.py) follow the fifth starter. Reflected where it belongs: the packaged templates (examples/task.md, examples/three-stage.md, the new examples/docs-fold.md), the packaged skill references (orchestration.md, format.md) and the repo guideline AGENTS.md all carry the new convention. No new reference file was added, so install.go's managed inventory is unchanged. The shared descriptive docs were deliberately not rewritten: this change makes README.md:191, docs/cli.md:170 and internal/author/skill/references/operations.md:13 name four starters where there are now five. Those stay as they are - correcting them now is exactly the per-item shared edit this change removes - and the stale-doc note docs/notes/docs-fold-single-writer.md records each one for the docs-fold writer to fold. Nothing else needed updating. No new dependency; no Android, Gradle, server, installer, Docker or published-definition change; no definition published over the running pipelines. Evidence: go test -count=1 ./... passed; go build ./... and go vet on the touched packages clean; ./internal/author/... covers embedding, reference links, the managed inventory and install/upgrade/protection; ./examples/... validates the fifth starter and its manual-only, committer-terminated graph; ./internal/server/... covers the served catalog. Not run: the docs-fold writer against the shared docs (nothing to fold yet); no install or deploy. (cherry picked from commit f29656cf084d7eee2e033f2a37a9d231d7acaaf0)
215 lines
6.7 KiB
Go
215 lines
6.7 KiB
Go
package examples_test
|
|
|
|
import (
|
|
"os"
|
|
"slices"
|
|
"testing"
|
|
|
|
"git.a-wan.net/alan/pipelines/examples"
|
|
"git.a-wan.net/alan/pipelines/internal/pipeline"
|
|
"git.a-wan.net/alan/pipelines/internal/protocol"
|
|
"git.a-wan.net/alan/pipelines/internal/stage"
|
|
)
|
|
|
|
func TestReadmeThreeStageExampleIsValid(t *testing.T) {
|
|
source, err := os.ReadFile("three-stage.md")
|
|
if err != nil {
|
|
t.Fatal(err)
|
|
}
|
|
graph, err := pipeline.Parse(string(source))
|
|
if err != nil {
|
|
t.Fatal(err)
|
|
}
|
|
if len(graph.Stages) != 4 || graph.Settings != nil {
|
|
t.Fatal("example must be manual-only and four stages")
|
|
}
|
|
}
|
|
|
|
func TestCatalogContainsValidUnpublishedTemplates(t *testing.T) {
|
|
items := examples.Catalog()
|
|
if len(items) != 5 {
|
|
t.Fatal("unexpected catalog size", len(items))
|
|
}
|
|
seen := map[string]bool{}
|
|
wantStages := map[string]int{"task": 2, "review": 1, "research": 2, "three-stage": 4, "docs-fold": 2}
|
|
for _, item := range items {
|
|
if seen[item.Key] || item.Description == "" || item.Name == "" {
|
|
t.Fatal("invalid template metadata", item.Key)
|
|
}
|
|
seen[item.Key] = true
|
|
graph, err := pipeline.Parse(item.Source)
|
|
if err != nil {
|
|
t.Fatal(item.Key, err)
|
|
}
|
|
if (graph.Settings != nil) != item.Scheduled {
|
|
t.Fatal("missing schedule warning", item.Key)
|
|
}
|
|
if graph.Settings != nil || len(graph.Stages) > 4 {
|
|
t.Fatal("starters must be small and manual-only", item.Key)
|
|
}
|
|
if len(graph.Stages) != wantStages[item.Key] {
|
|
t.Fatal("unexpected/non-generic catalog entry", item.Key)
|
|
}
|
|
}
|
|
}
|
|
|
|
// parsedCatalog parses every bundled starter once for the role/route assertions.
|
|
func parsedCatalog(t *testing.T) map[string]pipeline.Graph {
|
|
t.Helper()
|
|
parsed := map[string]pipeline.Graph{}
|
|
for _, item := range examples.Catalog() {
|
|
graph, err := pipeline.Parse(item.Source)
|
|
if err != nil {
|
|
t.Fatal(item.Key, err)
|
|
}
|
|
parsed[item.Key] = graph
|
|
}
|
|
return parsed
|
|
}
|
|
|
|
func stageTools(t *testing.T, graph pipeline.Graph, key string) ([]string, bool) {
|
|
t.Helper()
|
|
for _, s := range graph.Stages {
|
|
if s.Key != key {
|
|
continue
|
|
}
|
|
tools, explicit, err := stage.ToolNames(pipeline.StageDefinition(s))
|
|
if err != nil {
|
|
t.Fatalf("stage %s: %v", key, err)
|
|
}
|
|
sorted := slices.Clone(tools)
|
|
slices.Sort(sorted)
|
|
return sorted, explicit
|
|
}
|
|
t.Fatalf("stage %s not found", key)
|
|
return nil, false
|
|
}
|
|
|
|
// starterTools is the expected explicit role allowlist per template and stage.
|
|
// Every bundled starter declares a tools block; an empty list is the intentional
|
|
// deny-all tool-free role.
|
|
var starterTools = map[string]map[string][]string{
|
|
"task": {
|
|
"worker": {"read", "glob", "grep", "edit", "shell", "websearch", "webfetch"},
|
|
"committer": {"read", "glob", "grep", "shell"},
|
|
},
|
|
"review": {"review": {"read", "glob", "grep", "websearch", "webfetch"}},
|
|
"research": {
|
|
"research": {"websearch", "webfetch"},
|
|
"report": {},
|
|
},
|
|
"three-stage": {
|
|
"planner": {"read", "glob", "grep", "websearch", "webfetch"},
|
|
"implementer": {"read", "glob", "grep", "edit", "shell"},
|
|
"reviewer": {"read", "glob", "grep", "shell", "websearch", "webfetch"},
|
|
"committer": {"read", "glob", "grep", "shell"},
|
|
},
|
|
"docs-fold": {
|
|
"fold": {"read", "glob", "grep", "edit", "shell"},
|
|
"committer": {"read", "glob", "grep", "shell"},
|
|
},
|
|
}
|
|
|
|
func TestStarterRoleToolRestrictions(t *testing.T) {
|
|
parsed := parsedCatalog(t)
|
|
for key, stages := range starterTools {
|
|
graph, ok := parsed[key]
|
|
if !ok {
|
|
t.Fatalf("catalog entry %s missing", key)
|
|
}
|
|
for stageKey, want := range stages {
|
|
tools, explicit := stageTools(t, graph, stageKey)
|
|
if !explicit {
|
|
t.Fatalf("%s/%s must declare an explicit tools block", key, stageKey)
|
|
}
|
|
sortedWant := slices.Clone(want)
|
|
slices.Sort(sortedWant)
|
|
if !slices.Equal(tools, sortedWant) {
|
|
t.Fatalf("%s/%s tools = %v, want %v", key, stageKey, tools, sortedWant)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
func TestThreeStagePlannerBlockedRoute(t *testing.T) {
|
|
graph := parsedCatalog(t)["three-stage"]
|
|
for _, s := range graph.Stages {
|
|
if s.Key == "planner" {
|
|
if got := s.Edges["blocked"]; got != protocol.FailureEnd {
|
|
t.Fatalf("planner blocked route = %q, want %q", got, protocol.FailureEnd)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
func TestThreeStageReviewerMemoryKeepsPlannerAcceptance(t *testing.T) {
|
|
graph := parsedCatalog(t)["three-stage"]
|
|
var reviewer protocol.Stage
|
|
for _, s := range graph.Stages {
|
|
if s.Key == "reviewer" {
|
|
reviewer = s
|
|
}
|
|
}
|
|
if reviewer.Key == "" {
|
|
t.Fatal("three-stage reviewer stage missing")
|
|
}
|
|
plannerOwned := map[string]string{
|
|
"plan": "planner.plan",
|
|
"design": "planner.design",
|
|
"reuse_targets": "planner.reuse_targets",
|
|
"acceptance_checks": "planner.acceptance_checks",
|
|
"research": "planner.research",
|
|
}
|
|
for alias, reference := range plannerOwned {
|
|
if got := reviewer.Memory[alias]; got != reference {
|
|
t.Fatalf("reviewer memory %s = %q, want %q", alias, got, reference)
|
|
}
|
|
}
|
|
if got := reviewer.Memory["task"]; got != "input.prompt" {
|
|
t.Fatalf("reviewer must receive the original task, got %q", got)
|
|
}
|
|
for alias, want := range map[string]string{
|
|
"changed_files": "implementer.changed_files",
|
|
"implementation_summary": "implementer.implementation_summary",
|
|
"evidence": "implementer.evidence?",
|
|
} {
|
|
if got := reviewer.Memory[alias]; got != want {
|
|
t.Fatalf("reviewer memory %s = %q, want %q", alias, got, want)
|
|
}
|
|
}
|
|
}
|
|
|
|
// TestWorkProducingStartersEndInACommitter pins the guideline that a workflow
|
|
// which changes the repository commits locally through its final committer stage,
|
|
// staging the server-captured change set rather than only a model's declaration.
|
|
func TestWorkProducingStartersEndInACommitter(t *testing.T) {
|
|
for _, tc := range []struct{ key, producer string }{
|
|
{"task", "worker"},
|
|
{"three-stage", "implementer"},
|
|
{"docs-fold", "fold"},
|
|
} {
|
|
graph := parsedCatalog(t)[tc.key]
|
|
last := graph.Stages[len(graph.Stages)-1]
|
|
if last.Key != "committer" {
|
|
t.Fatalf("%s must end in a committer stage, got %q", tc.key, last.Key)
|
|
}
|
|
if got := last.Edges["success"]; got != protocol.SuccessEnd {
|
|
t.Fatalf("%s committer success route = %q, want %q", tc.key, got, protocol.SuccessEnd)
|
|
}
|
|
if got := last.Memory["server_changed_files"]; got != "input.server_changed_files" {
|
|
t.Fatalf("%s committer must select input.server_changed_files, got %q", tc.key, got)
|
|
}
|
|
if got := last.Memory["changed_files"]; got != tc.producer+".changed_files" {
|
|
t.Fatalf("%s committer changed_files = %q, want %q", tc.key, got, tc.producer+".changed_files")
|
|
}
|
|
// The producer hands its work on rather than ending the run itself.
|
|
for _, s := range graph.Stages {
|
|
if s.Key == tc.producer {
|
|
if protocol.IsTerminal(s.Edges["success"]) {
|
|
t.Fatalf("%s/%s must hand success to a later stage, not %q", tc.key, tc.producer, s.Edges["success"])
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|