From 41ceb09625ee81079c9c0349e6c30fc1f9ab54fd Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Wed, 18 Nov 2026 22:05:35 +0300 Subject: [PATCH 1/5] feat(runner): services --help shows megoocolab.toml's format (MC-69) Agents that create or update megoocolab.toml need its format: the keys of a set, the name rules, ${NAME} references, the reserved MEGOO_SERVICES_ prefix and that a .env file is never read. The text now lives once in services.Format, and `megoocolab-runner services --help` shows it, so a writable run can read it from the command. Later steps put the same text in a planning run's prompt. Co-Authored-By: Claude Opus 5.5 --- runner/cmd/services.go | 1 + runner/cmd/services_test.go | 11 +++++++++++ runner/internal/services/prompt.go | 22 +++++++++++++++++++++ runner/internal/services/prompt_test.go | 26 +++++++++++++++++++++++++ 4 files changed, 60 insertions(+) diff --git a/runner/cmd/services.go b/runner/cmd/services.go index f72920b..d27e09c 100644 --- a/runner/cmd/services.go +++ b/runner/cmd/services.go @@ -17,6 +17,7 @@ func newServicesCmd() *cobra.Command { cmd := &cobra.Command{ Use: "services", Short: "Start a worktree's test services for one command (megoocolab.toml)", + Long: "Start a worktree's test services for one command.\n\n" + services.Format, } cmd.AddCommand(newServicesRunCmd(), newServicesCleanCmd()) return cmd diff --git a/runner/cmd/services_test.go b/runner/cmd/services_test.go index 0ebc8c9..e8fcd6b 100644 --- a/runner/cmd/services_test.go +++ b/runner/cmd/services_test.go @@ -61,6 +61,17 @@ func runServices(t *testing.T, args ...string) (error, string, string) { return err, stdout.String(), stderr.String() } +func TestServicesHelpShowsTheFormat(t *testing.T) { + err, stdout, _ := runServices(t, "services", "--help") + if err != nil { + t.Fatalf("services --help = %v, want nil", err) + } + // Cobra trims the trailing whitespace of Long. + if !strings.Contains(stdout, strings.TrimSpace(services.Format)) { + t.Errorf("services --help does not show the format:\n%s", stdout) + } +} + func TestServicesRunExitsWithTheCommandsCode(t *testing.T) { servicesEnv(t) servicesWorktree(t) diff --git a/runner/internal/services/prompt.go b/runner/internal/services/prompt.go index 3bb77d7..eb0cae0 100644 --- a/runner/internal/services/prompt.go +++ b/runner/internal/services/prompt.go @@ -8,6 +8,28 @@ import ( "strings" ) +// Format is megoocolab.toml's format, for agents: a planning run gets it in its +// prompt, and `megoocolab-runner services --help` shows it to writable runs. +const Format = `megoocolab.toml, at the repository's root, declares the containers the checks need. Each [services.] table is a set: +- compose (required): one or more Docker Compose files, relative to megoocolab.toml. +- ports: names of variables. The runner picks a free port on 127.0.0.1 for each. +- env: more variables. A value may use ${NAME} for a port, for MEGOO_SERVICES_PROJECT (the set's unique Compose project name, also usable as an image tag), or for a variable already in the environment. +- description: optional, one line of at most 200 characters, shown to agents. +A set's name is a lowercase letter followed by lowercase letters and digits, with single hyphens between them, 20 characters at most. Variable names are those of environment variables; names starting with MEGOO_SERVICES_ are reserved. +The ports, the env entries and MEGOO_SERVICES_PROJECT go both to Docker Compose (so "127.0.0.1:${DB_PORT}:5432" works in a Compose file) and to the command. A .env file beside the Compose files is never read. +Example: + + [services.test] + description = "PostgreSQL for the backend tests" + compose = ["tools/test-services/docker-compose.yml"] + ports = ["DB_PORT"] + + [services.test.env] + DATABASE_URL = "postgresql://test:test@localhost:${DB_PORT}/test" + +Run a check with its set as: megoocolab-runner services run -- +` + // PromptSection is the text a writable run's prompt gets about the worktree's // service sets: "" when the worktree has no megoocolab.toml or it declares no // set. Only the worktree's own file counts, not one in a parent folder. diff --git a/runner/internal/services/prompt_test.go b/runner/internal/services/prompt_test.go index 0b330c7..c9dae1c 100644 --- a/runner/internal/services/prompt_test.go +++ b/runner/internal/services/prompt_test.go @@ -3,9 +3,35 @@ package services import ( "os" "path/filepath" + "reflect" + "regexp" + "strings" "testing" ) +func TestFormatNamesEveryKey(t *testing.T) { + typ := reflect.TypeOf(setDoc{}) + for i := 0; i < typ.NumField(); i++ { + tag := typ.Field(i).Tag.Get("toml") + // A key's line is "- key:" or "- key (required):". + line := regexp.MustCompile(`(?m)^- ` + regexp.QuoteMeta(tag) + `( \([^)]*\))?:`) + if !line.MatchString(Format) { + t.Errorf("Format does not describe the %q key", tag) + } + } + for _, want := range []string{ + "[services.]", + "${NAME}", + "MEGOO_SERVICES_", + ".env", + "megoocolab-runner services run -- ", + } { + if !strings.Contains(Format, want) { + t.Errorf("Format does not contain %q", want) + } + } +} + func TestPromptSection(t *testing.T) { write := func(t *testing.T, dir, name, content string) { t.Helper() From b726a32f679e1cc63db24d2ada5a9fd2321672ea Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Wed, 18 Nov 2026 22:09:39 +0300 Subject: [PATCH 2/5] feat(runner): planning text for megoocolab.toml and a reminder to keep it up to date (MC-69) PlanSection gives a planning run the text about megoocolab.toml: without the file, it asks for an "Add megoocolab.toml" first step when a check needs a container; with it, it says a step adding a check that needs a new service, port or variable changes the file in that same step. The file's format follows. PromptSection now ends with the same reminder for writable runs. Both share loadOwn and setList. Co-Authored-By: Claude Opus 5.5 --- runner/internal/services/prompt.go | 75 ++++++++++++++--- runner/internal/services/prompt_test.go | 106 ++++++++++++++++++++---- 2 files changed, 151 insertions(+), 30 deletions(-) diff --git a/runner/internal/services/prompt.go b/runner/internal/services/prompt.go index eb0cae0..ee53125 100644 --- a/runner/internal/services/prompt.go +++ b/runner/internal/services/prompt.go @@ -30,21 +30,77 @@ Example: Run a check with its set as: megoocolab-runner services run -- ` +// keepUpToDate ends a writable run's section. +const keepUpToDate = "If your work adds a check or a command that needs a service, a port or a variable the file does not " + + "declare, add it to `megoocolab.toml` (and its Compose files) in the same commit, and run the new check through it. " + + "`megoocolab-runner services --help` describes the file." + +// planKeep is the planning rule once the file exists. +const planKeep = "A step that adds a check or a command needing a service, a port or a variable the file does not declare " + + "changes `megoocolab.toml`, its Compose files and the repository's instructions for running checks in that same " + + "step, and runs the new check through `megoocolab-runner services run`." + +// planNoFile is the planning text for a repository without the file. +const planNoFile = "This repository has no `megoocolab.toml`. With one, the runner gives each worktree its own copy of the " + + "containers a check needs (a database, a search engine, the whole app) on free ports, and removes them when the " + + "check ends, so the checks of different tasks never share containers.\n" + + "Find out how this repository's checks get their services: Compose files, the CI configuration, the README, the " + + "test settings. If any check needs a container, make \"Add megoocolab.toml\" the plan's first step, and say in the " + + "plan that the runner asked for this step, not the design. That step writes `megoocolab.toml` (and a Compose file " + + "for the checks if the repository has none that fits), changes the repository's instructions for running its " + + "checks (AGENTS.md, README or the like) to use `megoocolab-runner services run -- `, and proves " + + "each set by running its check through it. Later steps run those checks the same way. If no check needs a " + + "container, add no step." + // PromptSection is the text a writable run's prompt gets about the worktree's // service sets: "" when the worktree has no megoocolab.toml or it declares no // set. Only the worktree's own file counts, not one in a parent folder. func PromptSection(worktree string) (string, error) { - path := filepath.Join(worktree, FileName) - if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) { - return "", nil + f, err := loadOwn(worktree) + if err != nil || f == nil || len(f.Sets) == 0 { + return "", err } - f, err := Load(path) + return "\n\n## Test services\nThis repository declares services for its checks in `megoocolab.toml`: " + + setList(f) + + ". Run every command that needs them as `megoocolab-runner services run -- `. " + + "It starts this worktree's own containers on free ports, gives your command the variables the file defines, " + + "and removes the containers when the command ends. Do not start, stop or reuse the project's containers any " + + "other way, and never touch containers you did not start. " + keepUpToDate + "\n", nil +} + +// PlanSection is the text a planning run's prompt gets about megoocolab.toml: +// how to add it in a worktree without one, how to keep it up to date in one +// with it, then the file's format. Only the worktree's own file counts. +func PlanSection(worktree string) (string, error) { + f, err := loadOwn(worktree) if err != nil { return "", err } - if len(f.Sets) == 0 { - return "", nil + var body string + switch { + case f == nil: + body = planNoFile + case len(f.Sets) == 0: + body = "This repository has a `megoocolab.toml` that declares no services yet. " + planKeep + default: + body = "This repository declares services for its checks in `megoocolab.toml`: " + setList(f) + + ". Steps run every command that needs them as `megoocolab-runner services run -- `. " + planKeep } + return "\n\n## Test services\n" + body + "\n\n" + Format, nil +} + +// loadOwn loads the worktree's own megoocolab.toml, not one in a parent +// folder: nil, nil when it has none. +func loadOwn(worktree string) (*File, error) { + path := filepath.Join(worktree, FileName) + if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + return Load(path) +} + +// setList names the sets for a prompt: `name` (description), sorted. +func setList(f *File) string { sets := make([]string, 0, len(f.Sets)) for _, name := range f.Names() { s := "`" + name + "`" @@ -53,10 +109,5 @@ func PromptSection(worktree string) (string, error) { } sets = append(sets, s) } - return "\n\n## Test services\nThis repository declares services for its checks in `megoocolab.toml`: " + - strings.Join(sets, ", ") + - ". Run every command that needs them as `megoocolab-runner services run -- `. " + - "It starts this worktree's own containers on free ports, gives your command the variables the file defines, " + - "and removes the containers when the command ends. Do not start, stop or reuse the project's containers any " + - "other way, and never touch containers you did not start.\n", nil + return strings.Join(sets, ", ") } diff --git a/runner/internal/services/prompt_test.go b/runner/internal/services/prompt_test.go index c9dae1c..74e7092 100644 --- a/runner/internal/services/prompt_test.go +++ b/runner/internal/services/prompt_test.go @@ -33,21 +33,10 @@ func TestFormatNamesEveryKey(t *testing.T) { } func TestPromptSection(t *testing.T) { - write := func(t *testing.T, dir, name, content string) { - t.Helper() - p := filepath.Join(dir, name) - if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { - t.Fatal(err) - } - if err := os.WriteFile(p, []byte(content), 0o644); err != nil { - t.Fatal(err) - } - } - t.Run("sets", func(t *testing.T) { wt := t.TempDir() - write(t, wt, "svc/compose.yml", "services: {}\n") - write(t, wt, FileName, `[services.test] + writeFile(t, wt, "svc/compose.yml", "services: {}\n") + writeFile(t, wt, FileName, `[services.test] description = "Postgres for the backend tests" compose = ["svc/compose.yml"] ports = ["DB_PORT"] @@ -59,7 +48,7 @@ compose = ["svc/compose.yml"] if err != nil { t.Fatal(err) } - want := "\n\n## Test services\nThis repository declares services for its checks in `megoocolab.toml`: `e2e`, `test` (Postgres for the backend tests). Run every command that needs them as `megoocolab-runner services run -- `. It starts this worktree's own containers on free ports, gives your command the variables the file defines, and removes the containers when the command ends. Do not start, stop or reuse the project's containers any other way, and never touch containers you did not start.\n" + want := "\n\n## Test services\nThis repository declares services for its checks in `megoocolab.toml`: `e2e`, `test` (Postgres for the backend tests). Run every command that needs them as `megoocolab-runner services run -- `. It starts this worktree's own containers on free ports, gives your command the variables the file defines, and removes the containers when the command ends. Do not start, stop or reuse the project's containers any other way, and never touch containers you did not start. If your work adds a check or a command that needs a service, a port or a variable the file does not declare, add it to `megoocolab.toml` (and its Compose files) in the same commit, and run the new check through it. `megoocolab-runner services --help` describes the file.\n" if got != want { t.Errorf("section =\n%q\nwant\n%q", got, want) } @@ -74,7 +63,7 @@ compose = ["svc/compose.yml"] t.Run("no sets", func(t *testing.T) { wt := t.TempDir() - write(t, wt, FileName, "# nothing yet\n") + writeFile(t, wt, FileName, "# nothing yet\n") got, err := PromptSection(wt) if got != "" || err != nil { t.Errorf("= %q, %v", got, err) @@ -83,7 +72,7 @@ compose = ["svc/compose.yml"] t.Run("invalid file", func(t *testing.T) { wt := t.TempDir() - write(t, wt, FileName, "[services.test]\ncompose = [\"missing.yml\"]\n") + writeFile(t, wt, FileName, "[services.test]\ncompose = [\"missing.yml\"]\n") got, err := PromptSection(wt) if got != "" || err == nil { t.Errorf("= %q, %v", got, err) @@ -92,8 +81,8 @@ compose = ["svc/compose.yml"] t.Run("only the worktree's own file", func(t *testing.T) { parent := t.TempDir() - write(t, parent, "svc/compose.yml", "services: {}\n") - write(t, parent, FileName, "[services.test]\ncompose = [\"svc/compose.yml\"]\n") + writeFile(t, parent, "svc/compose.yml", "services: {}\n") + writeFile(t, parent, FileName, "[services.test]\ncompose = [\"svc/compose.yml\"]\n") wt := filepath.Join(parent, "wt") if err := os.Mkdir(wt, 0o755); err != nil { t.Fatal(err) @@ -104,3 +93,84 @@ compose = ["svc/compose.yml"] } }) } + +func TestPlanSection(t *testing.T) { + const noFile = "This repository has no `megoocolab.toml`. With one, the runner gives each worktree its own copy of the containers a check needs (a database, a search engine, the whole app) on free ports, and removes them when the check ends, so the checks of different tasks never share containers.\n" + + "Find out how this repository's checks get their services: Compose files, the CI configuration, the README, the test settings. If any check needs a container, make \"Add megoocolab.toml\" the plan's first step, and say in the plan that the runner asked for this step, not the design. That step writes `megoocolab.toml` (and a Compose file for the checks if the repository has none that fits), changes the repository's instructions for running its checks (AGENTS.md, README or the like) to use `megoocolab-runner services run -- `, and proves each set by running its check through it. Later steps run those checks the same way. If no check needs a container, add no step." + const keep = "A step that adds a check or a command needing a service, a port or a variable the file does not declare changes `megoocolab.toml`, its Compose files and the repository's instructions for running checks in that same step, and runs the new check through `megoocolab-runner services run`." + section := func(body string) string { + return "\n\n## Test services\n" + body + "\n\n" + Format + } + + t.Run("no file", func(t *testing.T) { + got, err := PlanSection(t.TempDir()) + if err != nil { + t.Fatal(err) + } + if want := section(noFile); got != want { + t.Errorf("section =\n%q\nwant\n%q", got, want) + } + }) + + t.Run("sets", func(t *testing.T) { + wt := t.TempDir() + writeFile(t, wt, "svc/compose.yml", "services: {}\n") + writeFile(t, wt, FileName, `[services.test] +description = "Postgres for the backend tests" +compose = ["svc/compose.yml"] +ports = ["DB_PORT"] + +[services.e2e] +compose = ["svc/compose.yml"] +`) + got, err := PlanSection(wt) + if err != nil { + t.Fatal(err) + } + want := section("This repository declares services for its checks in `megoocolab.toml`: `e2e`, `test` (Postgres for the backend tests). Steps run every command that needs them as `megoocolab-runner services run -- `. " + keep) + if got != want { + t.Errorf("section =\n%q\nwant\n%q", got, want) + } + }) + + t.Run("no sets", func(t *testing.T) { + wt := t.TempDir() + writeFile(t, wt, FileName, "# nothing yet\n") + got, err := PlanSection(wt) + if err != nil { + t.Fatal(err) + } + if want := section("This repository has a `megoocolab.toml` that declares no services yet. " + keep); got != want { + t.Errorf("section =\n%q\nwant\n%q", got, want) + } + if strings.Contains(got, "Add megoocolab.toml") { + t.Errorf("section asks to add the file it already has:\n%s", got) + } + }) + + t.Run("invalid file", func(t *testing.T) { + wt := t.TempDir() + writeFile(t, wt, FileName, "[services.test]\ncompose = [\"missing.yml\"]\n") + got, err := PlanSection(wt) + if got != "" || err == nil { + t.Errorf("= %q, %v", got, err) + } + }) + + t.Run("only in a parent folder", func(t *testing.T) { + parent := t.TempDir() + writeFile(t, parent, "svc/compose.yml", "services: {}\n") + writeFile(t, parent, FileName, "[services.test]\ncompose = [\"svc/compose.yml\"]\n") + wt := filepath.Join(parent, "wt") + if err := os.Mkdir(wt, 0o755); err != nil { + t.Fatal(err) + } + got, err := PlanSection(wt) + if err != nil { + t.Fatal(err) + } + if want := section(noFile); got != want { + t.Errorf("section =\n%q\nwant\n%q", got, want) + } + }) +} From b1870c732bb365f3f32e042edddd9237930b7ff6 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Wed, 18 Nov 2026 22:14:29 +0300 Subject: [PATCH 3/5] feat(runner): planning runs are told to add or update megoocolab.toml (MC-69) A new helper, servicesPrompt, picks what a run's prompt gets about megoocolab.toml. A writable run gets the Test services section as before. The first run of a planning session (read-only, role plan, no session to resume) gets the planning section. Drafts, the other read-only roles and a continued planning session get nothing, whether the resume works or falls back to a new session. Co-Authored-By: Claude Opus 5.5 --- runner/internal/jobs/manager.go | 10 +-- runner/internal/jobs/services.go | 29 ++++++++ runner/internal/jobs/services_test.go | 99 ++++++++++++++++++++++++++- 3 files changed, 128 insertions(+), 10 deletions(-) diff --git a/runner/internal/jobs/manager.go b/runner/internal/jobs/manager.go index 902c88b..8599b76 100644 --- a/runner/internal/jobs/manager.go +++ b/runner/internal/jobs/manager.go @@ -29,7 +29,6 @@ import ( "github.com/mmhy2003/megoocolab/runner/internal/mask" "github.com/mmhy2003/megoocolab/runner/internal/policy" "github.com/mmhy2003/megoocolab/runner/internal/protocol" - "github.com/mmhy2003/megoocolab/runner/internal/services" "github.com/mmhy2003/megoocolab/runner/internal/startbranch" "github.com/mmhy2003/megoocolab/runner/internal/tools" "github.com/mmhy2003/megoocolab/runner/internal/worktree" @@ -956,14 +955,7 @@ func (m *Manager) drive(r *run, rs protocol.RunStart, agent protocol.WelcomeAgen return "cancelled", "" } - text := sess.prompt - if kind == policy.Workspace && rs.Draft == nil { - section, err := services.PromptSection(wt) - if err != nil { - fmt.Fprintf(logf, "runner: services: %v\n", err) - } - text += section - } + text := sess.prompt + servicesPrompt(rs, kind, wt, logf) prompt, err := r.content(text, rs.Images, imageData) if err != nil { return fail("images_failed", err) diff --git a/runner/internal/jobs/services.go b/runner/internal/jobs/services.go index 541fdc4..1ca4f6d 100644 --- a/runner/internal/jobs/services.go +++ b/runner/internal/jobs/services.go @@ -8,6 +8,8 @@ import ( "path/filepath" "time" + "github.com/mmhy2003/megoocolab/runner/internal/policy" + "github.com/mmhy2003/megoocolab/runner/internal/protocol" "github.com/mmhy2003/megoocolab/runner/internal/services" ) @@ -18,6 +20,33 @@ const ( servicesSweepEvery = time.Hour ) +// rolePlan is the workflow role of a planning run (RunStart.Role). +const rolePlan = "plan" + +// servicesPrompt is what a run's prompt gets about megoocolab.toml: a writable +// run the "Test services" section, the first run of a planning session the +// planning one, other runs (drafts, the other read-only roles, a continued +// planning session) nothing. An invalid file goes to the run's log and the +// run gets nothing. +func servicesPrompt(rs protocol.RunStart, kind policy.Kind, wt string, logf io.Writer) string { + var section func(string) (string, error) + switch { + case rs.Draft != nil: + return "" + case kind == policy.Workspace: + section = services.PromptSection + case kind == policy.ReadOnly && rs.Role == rolePlan && rs.ResumeSessionID == "": + section = services.PlanSection + default: + return "" + } + text, err := section(wt) + if err != nil { + fmt.Fprintf(logf, "runner: services: %v\n", err) + } + return text +} + // servicesDir is where this runner keeps the records of the service sets its // runs start. func (m *Manager) servicesDir() string { return filepath.Join(m.cacheRoot, "services") } diff --git a/runner/internal/jobs/services_test.go b/runner/internal/jobs/services_test.go index a0e3be6..6e60e41 100644 --- a/runner/internal/jobs/services_test.go +++ b/runner/internal/jobs/services_test.go @@ -57,11 +57,108 @@ func TestWritableRunGetsTheServicesSection(t *testing.T) { t.Fatalf("finished = %+v", f) } r := e.readReport() - if len(r.Prompts) == 0 || !strings.Contains(r.Prompts[0], "## Test services") || !strings.Contains(r.Prompts[0], "`test`") { + if len(r.Prompts) == 0 || !strings.Contains(r.Prompts[0], "## Test services") || !strings.Contains(r.Prompts[0], "`test`") || + !strings.Contains(r.Prompts[0], "`megoocolab-runner services --help` describes the file") { t.Fatalf("prompts = %q", r.Prompts) } } +// planRun makes a run the read-only first run of a planning session. +func planRun(rs *protocol.RunStart) { rs.Policy, rs.Role = "read_only", "plan" } + +func TestPlanRunGetsThePlanSection(t *testing.T) { + for _, tc := range []struct { + name string + files bool + parts []string + }{ + {"without the file", false, []string{"This repository has no `megoocolab.toml`", "Add megoocolab.toml"}}, + {"with the file", true, []string{"`test`", "changes `megoocolab.toml`"}}, + } { + t.Run(tc.name, func(t *testing.T) { + e := newEnvWithCache(t, `[{"say":"done"}]`, 1, t.TempDir()) + if tc.files { + commitFiles(t, e.repo, servicesFiles) + } + e.startRunWith("run-1", "MEG-1", planRun) + if f := e.finished("run-1"); f.Outcome != "completed" { + t.Fatalf("finished = %+v", f) + } + r := e.readReport() + if len(r.Prompts) == 0 { + t.Fatal("no prompt") + } + for _, part := range tc.parts { + if !strings.Contains(r.Prompts[0], part) { + t.Fatalf("prompt lacks %q: %q", part, r.Prompts[0]) + } + } + want, err := services.PlanSection(e.worktree("MEG-1")) + if err != nil { + t.Fatal(err) + } + if r.Prompts[0] != "please"+want { + t.Fatalf("prompt = %q, want %q", r.Prompts[0], "please"+want) + } + }) + } +} + +func TestOtherReadOnlyRunsGetNoPlanSection(t *testing.T) { + for _, role := range []string{"", "brainstorm", "final_review", "pr_review"} { + t.Run("role "+role, func(t *testing.T) { + e := newEnvWithCache(t, `[{"say":"done"}]`, 1, t.TempDir()) + e.startRunWith("run-1", "MEG-1", func(rs *protocol.RunStart) { rs.Policy, rs.Role = "read_only", role }) + if f := e.finished("run-1"); f.Outcome != "completed" { + t.Fatalf("finished = %+v", f) + } + r := e.readReport() + if len(r.Prompts) == 0 || strings.Contains(r.Prompts[0], "## Test services") { + t.Fatalf("prompts = %q", r.Prompts) + } + }) + } +} + +func TestContinuedPlanSessionGetsNoSection(t *testing.T) { + t.Setenv("FAKEAGENT_SESSIONS_DIR", t.TempDir()) + e := newEnvWithCache(t, twoTurns, 1, t.TempDir()) + e.startRunWith("run-a", "MEG-1", func(rs *protocol.RunStart) { planRun(rs); rs.Prompt = "first turn" }) + first := e.finished("run-a") + if first.Outcome != "completed" || first.SessionID == nil { + t.Fatalf("finished = %+v", first) + } + if r := e.finalReport(); len(r.Prompts) == 0 || !strings.Contains(r.Prompts[0], "## Test services") { + t.Fatalf("first prompts = %q", r.Prompts) + } + + e.startRunWith("run-b", "MEG-1", func(rs *protocol.RunStart) { + planRun(rs) + rs.ResumeSessionID, rs.ResumePrompt = *first.SessionID, "continue please" + }) + if f := e.finished("run-b"); f.Outcome != "completed" { + t.Fatalf("finished = %+v", f) + } + if r := e.finalReport(); !slices.Equal(r.Prompts, []string{"continue please"}) { + t.Fatalf("prompts = %q", r.Prompts) + } + + t.Run("fallback", func(t *testing.T) { + t.Setenv("FAKEAGENT_SESSIONS_DIR", t.TempDir()) + e := newEnvWithCache(t, twoTurns, 1, t.TempDir()) + e.startRunWith("run-fb", "MEG-1", func(rs *protocol.RunStart) { + planRun(rs) + rs.Prompt, rs.ResumePrompt, rs.ResumeSessionID = "full prompt", "continue please", "fake-session-404" + }) + if f := e.finished("run-fb"); f.Outcome != "completed" { + t.Fatalf("finished = %+v", f) + } + if r := e.finalReport(); !slices.Equal(r.Prompts, []string{"full prompt\n\ncontinue please"}) { + t.Fatalf("prompts = %q", r.Prompts) + } + }) +} + func TestReadOnlyRunAndRunsWithoutTheFileGetNoSection(t *testing.T) { for _, tc := range []struct { name, policy string From e3719d020e9bbfb95a688d896039e0a6d514e03d Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Wed, 18 Nov 2026 22:20:13 +0300 Subject: [PATCH 4/5] docs(runner): what planning and writable runs are told about megoocolab.toml (MC-69) The Test services section of the runner README now says that writable runs are asked to add a service, port or variable that new work needs to the file in the same commit, and that the first run of a planning session is told to add the file as the plan's first step, or to change it in the step that needs it. Co-Authored-By: Claude Opus 5.5 --- runner/README.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/runner/README.md b/runner/README.md index dcbedbd..8b7b511 100644 --- a/runner/README.md +++ b/runner/README.md @@ -169,9 +169,18 @@ Services are removed in three places, so nothing keeps running: removed. `services clean` does the same by hand. Writable runs (implement, the fix roles, finish, freestyle, crons) in a worktree with `megoocolab.toml` get a -"Test services" section in their prompt that names the sets and the command. The runner puts its own folder first -on the agent's `PATH` and sets `MEGOO_SERVICES_DIR`, so the agent's checks and the runner share the same records. -Read-only runs get nothing. +"Test services" section in their prompt. It names the sets and the command, and asks the agent to add any service, +port or variable that new work needs to the file in the same commit. The runner puts its own folder first on the +agent's `PATH` and sets `MEGOO_SERVICES_DIR`, so the agent's checks and the runner share the same records. +`megoocolab-runner services --help` prints the file's format. + +The first run of a planning session gets a section too. Without `megoocolab.toml`, the planning agent is asked to +find out whether any check needs a container, and if one does, to make "Add megoocolab.toml" the plan's first step. +That step writes the file, points the repository's check instructions at `services run` and proves each set. With +the file, the agent is told that a step adding a check that needs a new service, port or variable changes the file +in that same step. Both include the file's format, because a planning run cannot run commands. A plan session +continued with an answer or a rejection, the other read-only runs and Knowledge Base drafts get nothing. To stop +the suggestion for a repository, commit an empty `megoocolab.toml`. The runner only removes Compose projects it recorded itself, and only names of the form `megoo-…-<8 hex>`. Other containers, such as a MegooColab instance's `megoocolab-*` containers, are never touched. From 9580492ed5ee6363cbf6a66aaf84a12a1e2fec37 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Wed, 18 Nov 2026 22:21:46 +0300 Subject: [PATCH 5/5] docs: MC-69 design and plan --- docs/superpowers/plans/MC-69-plan.md | 258 +++++++++++++++++++++++++ docs/superpowers/specs/MC-69-design.md | 71 +++++++ 2 files changed, 329 insertions(+) create mode 100644 docs/superpowers/plans/MC-69-plan.md create mode 100644 docs/superpowers/specs/MC-69-design.md diff --git a/docs/superpowers/plans/MC-69-plan.md b/docs/superpowers/plans/MC-69-plan.md new file mode 100644 index 0000000..6454dea --- /dev/null +++ b/docs/superpowers/plans/MC-69-plan.md @@ -0,0 +1,258 @@ +# MC-69 implementation plan: planning runs are told to add `megoocolab.toml`, and every run is reminded to keep it up to date + +**Goal:** a new planning session in a worktree without `megoocolab.toml` is told to make "Add megoocolab.toml" the plan's first step when a check needs containers. A planning session in a worktree with the file, and every writable run, is told to change the file in the same step or commit that adds a check needing a new service, port or variable. + +**Architecture:** only the runner changes. `runner/internal/services/prompt.go` gets the `Format` constant, a new `PlanSection(worktree)` and one more sentence in `PromptSection`. `runner/internal/jobs/services.go` gets one helper, `servicesPrompt`, that picks the section for a run (writable: `PromptSection`; read-only, role `plan`, not a continued session: `PlanSection`; others: nothing). `manager.go` calls it in place of today's inline block. `megoocolab-runner services --help` prints `Format`. The README says what runs are told. + +## Conventions for every step + +- Work on the existing branch `megoo/MC-69-megoocolab-toml-creation`. One commit per step, subject `type(area): what changed (MC-69)` (AGENTS.md "Commits"), body in plain sentences, ending with `Co-Authored-By: Claude Opus 5.5 `. Never commit `.megoocolab/`. +- TDD: write the test, run it and see it fail (a compile error for a new symbol counts), implement, run it again. Commands run from `runner/`. Before each commit, `go test ./...` and `go vet ./...` pass in `runner/`. +- Do not change `runner/VERSION`. No change to the backend, the frontend, the server protocol or the file's format. No new dependency. + +## One point the design left open, decided here + +**What "a new session" means.** `openSession` (`internal/jobs/session.go`) can start a new session for a run that asked to resume one (`fresh`, or after a failed resume). That new session gets the full prompt plus the resume prompt (an answer or a rejection). The planning section is therefore added only when `rs.ResumeSessionID == ""`: the plan stage's first run. A continued run gets nothing, whether the resume works or falls back. This way a rejection such as "drop that step" is never followed by a repeated instruction to add it, which is the design's reason for the rule. + +## File map + +| File | Change | +|---|---| +| `runner/internal/services/prompt.go` | `Format` (new), `PlanSection` (new), `loadOwn` and `setList` (new private helpers taken from `PromptSection`), the reminder sentence added to `PromptSection`. | +| `runner/internal/services/prompt_test.go` | Tests for `Format`, `PlanSection` and the new sentence. | +| `runner/cmd/services.go` | `Long` help of the `services` command shows `Format`. | +| `runner/cmd/services_test.go` | `services --help` test. | +| `runner/internal/jobs/services.go` | `rolePlan` constant and `servicesPrompt` helper. | +| `runner/internal/jobs/manager.go` | Line ~959: `text := sess.prompt + servicesPrompt(rs, kind, wt, logf)` replaces the inline `PromptSection` block. | +| `runner/internal/jobs/services_test.go` | Plan-role, other-role, resumed-session and writable-sentence tests. | +| `runner/README.md` | "Test services": the paragraph on what runs are told. | + +## Code the steps share + +### `Format` (step 1, `runner/internal/services/prompt.go`) + +```go +// Format is megoocolab.toml's format, for agents: a planning run gets it in its +// prompt, and `megoocolab-runner services --help` shows it to writable runs. +const Format = `megoocolab.toml, at the repository's root, declares the containers the checks need. Each [services.] table is a set: +- compose (required): one or more Docker Compose files, relative to megoocolab.toml. +- ports: names of variables. The runner picks a free port on 127.0.0.1 for each. +- env: more variables. A value may use ${NAME} for a port, for MEGOO_SERVICES_PROJECT (the set's unique Compose project name, also usable as an image tag), or for a variable already in the environment. +- description: optional, one line of at most 200 characters, shown to agents. +A set's name is a lowercase letter followed by lowercase letters and digits, with single hyphens between them, 20 characters at most. Variable names are those of environment variables; names starting with MEGOO_SERVICES_ are reserved. +The ports, the env entries and MEGOO_SERVICES_PROJECT go both to Docker Compose (so "127.0.0.1:${DB_PORT}:5432" works in a Compose file) and to the command. A .env file beside the Compose files is never read. +Example: + + [services.test] + description = "PostgreSQL for the backend tests" + compose = ["tools/test-services/docker-compose.yml"] + ports = ["DB_PORT"] + + [services.test.env] + DATABASE_URL = "postgresql://test:test@localhost:${DB_PORT}/test" + +Run a check with its set as: megoocolab-runner services run -- +` +``` + +### `prompt.go` after step 2 + +```go +// keepUpToDate ends a writable run's section. +const keepUpToDate = "If your work adds a check or a command that needs a service, a port or a variable the file does not " + + "declare, add it to `megoocolab.toml` (and its Compose files) in the same commit, and run the new check through it. " + + "`megoocolab-runner services --help` describes the file." + +// planKeep is the planning rule once the file exists. +const planKeep = "A step that adds a check or a command needing a service, a port or a variable the file does not declare " + + "changes `megoocolab.toml`, its Compose files and the repository's instructions for running checks in that same " + + "step, and runs the new check through `megoocolab-runner services run`." + +// planNoFile is the planning text for a repository without the file. +const planNoFile = "This repository has no `megoocolab.toml`. With one, the runner gives each worktree its own copy of the " + + "containers a check needs (a database, a search engine, the whole app) on free ports, and removes them when the " + + "check ends, so the checks of different tasks never share containers.\n" + + "Find out how this repository's checks get their services: Compose files, the CI configuration, the README, the " + + "test settings. If any check needs a container, make \"Add megoocolab.toml\" the plan's first step, and say in the " + + "plan that the runner asked for this step, not the design. That step writes `megoocolab.toml` (and a Compose file " + + "for the checks if the repository has none that fits), changes the repository's instructions for running its " + + "checks (AGENTS.md, README or the like) to use `megoocolab-runner services run -- `, and proves " + + "each set by running its check through it. Later steps run those checks the same way. If no check needs a " + + "container, add no step." + +// PromptSection is the text a writable run's prompt gets about the worktree's +// service sets: "" when the worktree has no megoocolab.toml or it declares no +// set. Only the worktree's own file counts, not one in a parent folder. +func PromptSection(worktree string) (string, error) { + f, err := loadOwn(worktree) + if err != nil || f == nil || len(f.Sets) == 0 { + return "", err + } + return "\n\n## Test services\nThis repository declares services for its checks in `megoocolab.toml`: " + + setList(f) + + ". Run every command that needs them as `megoocolab-runner services run -- `. " + + "It starts this worktree's own containers on free ports, gives your command the variables the file defines, " + + "and removes the containers when the command ends. Do not start, stop or reuse the project's containers any " + + "other way, and never touch containers you did not start. " + keepUpToDate + "\n", nil +} + +// PlanSection is the text a planning run's prompt gets about megoocolab.toml: +// how to add it in a worktree without one, how to keep it up to date in one +// with it, then the file's format. Only the worktree's own file counts. +func PlanSection(worktree string) (string, error) { + f, err := loadOwn(worktree) + if err != nil { + return "", err + } + var body string + switch { + case f == nil: + body = planNoFile + case len(f.Sets) == 0: + body = "This repository has a `megoocolab.toml` that declares no services yet. " + planKeep + default: + body = "This repository declares services for its checks in `megoocolab.toml`: " + setList(f) + + ". Steps run every command that needs them as `megoocolab-runner services run -- `. " + planKeep + } + return "\n\n## Test services\n" + body + "\n\n" + Format, nil +} + +// loadOwn loads the worktree's own megoocolab.toml, not one in a parent +// folder: nil, nil when it has none. +func loadOwn(worktree string) (*File, error) { + path := filepath.Join(worktree, FileName) + if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + return Load(path) +} + +// setList names the sets for a prompt: `name` (description), sorted. +func setList(f *File) string { + sets := make([]string, 0, len(f.Sets)) + for _, name := range f.Names() { + s := "`" + name + "`" + if d := f.Sets[name].Description; d != "" { + s += " (" + d + ")" + } + sets = append(sets, s) + } + return strings.Join(sets, ", ") +} +``` + +### `servicesPrompt` (step 3, `runner/internal/jobs/services.go`) + +```go +// rolePlan is the workflow role of a planning run (RunStart.Role). +const rolePlan = "plan" + +// servicesPrompt is what a run's prompt gets about megoocolab.toml: a writable +// run the "Test services" section, the first run of a planning session the +// planning one, other runs (drafts, the other read-only roles, a continued +// planning session) nothing. An invalid file goes to the run's log and the +// run gets nothing. +func servicesPrompt(rs protocol.RunStart, kind policy.Kind, wt string, logf io.Writer) string { + var section func(string) (string, error) + switch { + case rs.Draft != nil: + return "" + case kind == policy.Workspace: + section = services.PromptSection + case kind == policy.ReadOnly && rs.Role == rolePlan && rs.ResumeSessionID == "": + section = services.PlanSection + default: + return "" + } + text, err := section(wt) + if err != nil { + fmt.Fprintf(logf, "runner: services: %v\n", err) + } + return text +} +``` + +In `manager.go` (around line 959) this: + +```go + text := sess.prompt + if kind == policy.Workspace && rs.Draft == nil { + section, err := services.PromptSection(wt) + if err != nil { + fmt.Fprintf(logf, "runner: services: %v\n", err) + } + text += section + } +``` + +becomes `text := sess.prompt + servicesPrompt(rs, kind, wt, logf)`. Remove the `services` import from `manager.go` only if nothing else there uses it (`go build` says so). + +## Steps + +### 1. feat(runner): `services --help` shows megoocolab.toml's format + +- **Tests first.** + - `runner/internal/services/prompt_test.go`: add `TestFormatNamesEveryKey`. It goes over `reflect.TypeOf(setDoc{})` fields and reads each `toml` tag (`description`, `compose`, `ports`, `env`). For each tag it checks that `Format` contains `"- " + tag + ":"`, and that `Format` contains `[services.]`, `${NAME}`, `MEGOO_SERVICES_`, `.env` and `megoocolab-runner services run -- `. A key added to the loader later then fails this test until `Format` documents it. + - `runner/cmd/services_test.go`: add `TestServicesHelpShowsTheFormat`. `err, stdout, _ := runServices(t, "services", "--help")`, then `err == nil` and `strings.Contains(stdout, strings.TrimSpace(services.Format))`. Cobra trims trailing whitespace of `Long`, hence `TrimSpace`. +- Run `go test ./internal/services/ ./cmd/ -run 'TestFormatNamesEveryKey|TestServicesHelpShowsTheFormat'`. Expected: compile error, `undefined: Format`. +- **Implement.** Add `Format` to `prompt.go` exactly as in "Code the steps share". In `cmd/services.go` `newServicesCmd`, add `Long: "Start a worktree's test services for one command.\n\n" + services.Format,`. +- Run the same command: it passes. Then `go test ./...` and `go vet ./...`. +- Commit: `feat(runner): services --help shows megoocolab.toml's format (MC-69)`. + +### 2. feat(runner): planning text for megoocolab.toml and the keep-it-up-to-date sentence + +- **Tests first** in `runner/internal/services/prompt_test.go`. Reuse the `write` helper in `TestPromptSection` by moving it to a top-level `writeFile(t, dir, name, content)` in that file. + - `TestPromptSection/sets`: `want` gets `" " + keepUpToDate` before the final `"\n"`. Write the sentence out literally in the test, not the constant: `"... never touch containers you did not start. If your work adds a check or a command that needs a service, a port or a variable the file does not declare, add it to `megoocolab.toml` (and its Compose files) in the same commit, and run the new check through it. `megoocolab-runner services --help` describes the file.\n"`. The other subtests stay as they are. + - New `TestPlanSection` with subtests. Each subtest compares with `"\n\n## Test services\n" + body + "\n\n" + Format`, with `body` written out literally: + - `no file`: empty `t.TempDir()`, body is the `planNoFile` text. + - `sets`: the same two-set file as `TestPromptSection/sets`. Body: "This repository declares services for its checks in `megoocolab.toml`: `e2e`, `test` (Postgres for the backend tests). Steps run every command that needs them as `megoocolab-runner services run -- `. " + the planKeep text. + - `no sets`: file `# nothing yet\n`. Body: "This repository has a `megoocolab.toml` that declares no services yet. " + the planKeep text. It must not contain `Add megoocolab.toml`. + - `invalid file`: `[services.test]\ncompose = ["missing.yml"]\n`. Expect `""` and a non-nil error. + - `only in a parent folder`: as in `TestPromptSection`. Expect the `no file` text and a nil error. +- Run `go test ./internal/services/ -run 'TestPromptSection|TestPlanSection'`. Expected: compile error `undefined: PlanSection`, and `sets` would fail on the missing sentence. +- **Implement** `prompt.go` as in "`prompt.go` after step 2". Add the `keepUpToDate`, `planKeep` and `planNoFile` constants, plus `PlanSection`, `loadOwn` and `setList`, and rewrite `PromptSection` on top of the helpers. +- Run again: pass. `go test ./...` (the jobs tests check only `Contains`, so they still pass) and `go vet ./...`. +- Commit: `feat(runner): planning text for megoocolab.toml and a reminder to keep it up to date (MC-69)`. + +### 3. feat(runner): planning runs get the megoocolab.toml section + +- **Tests first** in `runner/internal/jobs/services_test.go`. Use the existing helpers: `newEnvWithCache`, `commitFiles`, `servicesFiles`, `startRunWith`, `finished`, `readReport`, `finalReport`, and `twoTurns` from `resume_test.go`. + - `TestPlanRunGetsThePlanSection`, with subtests `without the file` and `with the file`. Each runs `startRunWith("run-1", "MEG-1", func(rs) { rs.Policy = "read_only"; rs.Role = "plan" })` and expects outcome `completed`. Then: + - without the file: `Prompts[0]` contains "This repository has no `megoocolab.toml`" and `Add megoocolab.toml`; + - with the file (`commitFiles(t, e.repo, servicesFiles)` first): `Prompts[0]` contains "`test`" and "changes `megoocolab.toml`". + - Both: `Prompts[0] == "please" + want`, where `want, _ := services.PlanSection(e.worktree("MEG-1"))`. + - `TestOtherReadOnlyRunsGetNoPlanSection`: a table of roles `""`, `"brainstorm"`, `"final_review"`, `"pr_review"`, all read-only with no file. `Prompts[0]` must not contain `## Test services`. + - `TestContinuedPlanSessionGetsNoSection`: `t.Setenv("FAKEAGENT_SESSIONS_DIR", t.TempDir())`, with `twoTurns`. + - run-a: read-only, role plan, `Prompt = "first turn"`, no file. Its prompt contains `## Test services`. + - run-b: read-only, role plan, `ResumeSessionID = *first.SessionID`, `ResumePrompt = "continue please"`. Prompts are exactly `["continue please"]`. + - Subtest `fallback`: read-only, role plan, `Prompt = "full prompt"`, `ResumePrompt = "continue please"`, `ResumeSessionID = "fake-session-404"`. Prompts are exactly `["full prompt\n\ncontinue please"]`. + - In `TestWritableRunGetsTheServicesSection`, also require "`megoocolab-runner services --help` describes the file". `TestReadOnlyRunAndRunsWithoutTheFileGetNoSection` stays and covers a writable run without the file. +- Run `go test ./internal/jobs/ -run 'Plan|TestWritableRunGetsTheServicesSection'`. Expected: the plan subtests fail (no section). +- **Implement** `rolePlan` and `servicesPrompt` in `internal/jobs/services.go` (code in "Code the steps share"; add imports `protocol` and `policy`). Replace the block in `manager.go` with `text := sess.prompt + servicesPrompt(rs, kind, wt, logf)`. +- Run again: pass. `go test ./...` and `go vet ./...`. +- Commit: `feat(runner): planning runs are told to add or update megoocolab.toml (MC-69)`. + +### 4. docs(runner): README says what planning and writable runs are told about megoocolab.toml + +- In `runner/README.md` "Test services", replace the paragraph that starts "Writable runs (implement, the fix roles, finish, freestyle, crons) in a worktree with `megoocolab.toml`..." and ends "Read-only runs get nothing." with: + + > Writable runs (implement, the fix roles, finish, freestyle, crons) in a worktree with `megoocolab.toml` get a "Test services" section in their prompt. It names the sets and the command, and asks the agent to add any service, port or variable that new work needs to the file in the same commit. The runner puts its own folder first on the agent's `PATH` and sets `MEGOO_SERVICES_DIR`, so the agent's checks and the runner share the same records. `megoocolab-runner services --help` prints the file's format. + > + > The first run of a planning session gets a section too. Without `megoocolab.toml`, the planning agent is asked to find out whether any check needs a container, and if one does, to make "Add megoocolab.toml" the plan's first step. That step writes the file, points the repository's check instructions at `services run` and proves each set. With the file, the agent is told that a step adding a check that needs a new service, port or variable changes the file in that same step. Both include the file's format, because a planning run cannot run commands. A plan session continued with an answer or a rejection, the other read-only runs and Knowledge Base drafts get nothing. To stop the suggestion for a repository, commit an empty `megoocolab.toml`. +- No test; check with `go test ./...` that nothing else changed. +- Commit: `docs(runner): what planning and writable runs are told about megoocolab.toml (MC-69)`. + +## Final verification + +From `runner/`: + +```bash +go vet ./... +go test ./... +go run . services --help # prints the format +``` + +By hand before merging (from the design; needs a runner built from the branch and the server, outside an agent session): +- plan a task in a repository without the file whose tests need a database: the plan's first step is "Add megoocolab.toml", marked as asked for by the runner; +- plan one in a repository whose tests need nothing: no such step; +- in this repository, plan a task that adds a check needing a new service: that step changes `megoocolab.toml`. diff --git a/docs/superpowers/specs/MC-69-design.md b/docs/superpowers/specs/MC-69-design.md new file mode 100644 index 0000000..768bc00 --- /dev/null +++ b/docs/superpowers/specs/MC-69-design.md @@ -0,0 +1,71 @@ +# MC-69 design: the runner gets `megoocolab.toml` created as a plan step, and reminds agents to keep it up to date + +## Goal + +When a task is planned in a repository that has no `megoocolab.toml` and whose checks need containers, the plan gets a first step that creates the file, so you approve it with the plan. Once the file exists, agents are reminded in every task to update it whenever new tests or commands need a service it does not declare. Mockup v2 shows both flows. + +## Decisions + +- **Created as a step in the task's plan** (your answer). The runner tells the planning agent the file is missing; the agent adds the step only when a check needs a container; you approve it with the plan; it is built and reviewed as its own commit. Rejected: creating it right away inside any writable run (arrives unannounced in a task about something else), and a task of its own on the board (needs server and web app changes, and checks keep sharing containers until it is merged). +- **Kept up to date** (your instruction of 18:50 UTC). Two reminders: + - the planning agent is told that a step adding a check or a command that needs a new service, port or variable changes the file in that same step; + - every writable run gets one more sentence in today's "Test services" section saying the same for its own work. This covers fix runs, freestyle chats and crons, which have no plan. +- **The file's format does not change.** It declares services (Compose files, ports, variables), not check commands. I read "new commands or tests require adding" as: a new check that needs a set, a port or a variable the file lacks. Check commands stay in the repository's own instructions (AGENTS.md, README), which the creating step updates. If you meant that the file should also list the commands, reject this design and say so: that is a format change. +- **Only the runner changes**, as in MC-52: the server does not know the file. The runner reads the worktree and adds text to the prompt. +- **The agent decides whether containers are needed**, from the repository itself (Compose files, CI configuration, README, test settings). If no check needs one, no step is added and nothing is created. +- **The format is written once** in the runner and used in three places: the two planning sections and `megoocolab-runner services --help`. A planning run is read-only and cannot run the command, so it gets the text in its prompt; writable runs are pointed to the command. +- **The planning section is added only to a new session.** A session resumed with your answer or your rejection already has it, so a rejection such as "drop that step" is not contradicted by a repeated instruction. + +## Architecture + +All in `runner/`: + +- `internal/services/prompt.go` + - `Format` (new constant): the file's format in about ten lines, taken from the runner README's "Test services" section (the keys, the name rules, `${NAME}`, the reserved `MEGOO_SERVICES_` prefix, that a `.env` is not read). + - `PlanSection(worktree)` (new): the text for a planning run, one of three: + - **no file**: the repository has no `megoocolab.toml`; what the file gives (each worktree's own containers per check, on free ports, removed afterwards); find out how the checks get their services; if any check needs a container, make "Add megoocolab.toml" the plan's first step and say in the plan that the runner asked for it, not the design; the step writes the file (and a Compose file for the checks if the repository has none that fits), changes the repository's instructions for running checks to use `megoocolab-runner services run -- `, and proves each set by running its check through it; later steps run those checks the same way; if no check needs a container, add no step. Then `Format`. + - **file with sets**: the set names and descriptions, as today's section lists them; steps run commands that need them through `services run`; a step that adds a check or a command needing a service, a port or a variable the file does not declare changes `megoocolab.toml`, its Compose files and the repository's instructions in that same step. Then `Format`. + - **file with no sets**: the same rule, saying the file declares no services yet. No creation step is suggested. + - `PromptSection(worktree)` (changed): the existing section for writable runs gets the sentence "If your work adds a check or a command that needs a service, a port or a variable the file does not declare, add it to `megoocolab.toml` (and its Compose files) in the same commit, and run the new check through it. `megoocolab-runner services --help` describes the file." A worktree without the file, or with no sets, still gets nothing. +- `internal/jobs/manager.go`: next to today's call for writable runs, a read-only run with `role == "plan"` on a new session gets `PlanSection`. An error is written to the run's log and the run goes on, as today. +- `cmd/services.go`: the `services` command's long help shows `Format`. +- `runner/README.md`: the paragraph on what runs are told, in "Test services". + +## Data and interfaces + +- **No change** to the file's format, the server protocol, the database, the API or the web app. `role` is already sent in `run_start`; the runner starts using it. +- **New prompt text** for planning runs; one new sentence for writable runs. +- **`megoocolab-runner services --help`** prints the format. + +## Error handling and edge cases + +- **An invalid `megoocolab.toml`:** the error goes to the run's log and no section is added, as today. Text of an error never reaches a prompt. +- **What reaches the prompt from the file** stays as in MC-52: set names (checked against the name rule) and descriptions (one line, 200 characters at most). +- **You do not want the step:** reject the plan and say so. To stop the suggestion for a repository for good, commit an empty `megoocolab.toml`. +- **Two tasks planned before either is merged** both get the step. The second to merge has a conflict in the file, which the finish stage resolves like any other conflict. +- **Docker is missing on the runner's computer:** the step cannot prove the file; `services run` says so and the implementing agent asks you, as with any failing check. +- **The reviewers:** the step is in the approved plan and marked as asked for by the runner, so the step review and the final review do not treat it as work nobody asked for. +- **Other read-only runs** (brainstorm, the reviews, pull-request review) and Knowledge Base draft runs get nothing. +- **A plan session started by an older runner and resumed by the new one** does not get the section. It gets it at the next task. + +## Testing + +Tests are written first. + +- **`runner/internal/services`** (`prompt_test.go`): the exact text of `PlanSection` for no file, a file with sets, a file with no sets, an invalid file (error, no text) and a file only in a parent folder (counts as no file); the new sentence in `PromptSection`; `Format` names every key the loader accepts. +- **`runner/internal/jobs`** (`services_test.go`, with the fake agent): + - a read-only run with role `plan` gets the "no file" section in a worktree without the file, and the "keep it up to date" section with it; + - read-only runs with another role, or none, get nothing; + - a resumed plan session gets nothing; + - a writable run with the file gets the new sentence, and one without the file still gets nothing. +- **`runner/cmd`:** `services --help` prints the format. +- **By hand before merging:** plan a task in a repository without the file whose tests need a database, and see the step in the plan; plan one in a repository whose tests need nothing, and see no step; in this repository, plan a task that adds a check needing a new service, and see the change to `megoocolab.toml` in that step. + +## Out of scope + +- Creating the file outside a plan: freestyle chats, crons and fix runs do not create it. They only keep an existing one up to date. +- Listing check commands in `megoocolab.toml`, or any other change to its format. +- Anything in the server or the web app: no setting, no notice that a project has no file, no task created automatically. +- Telling the brainstorm stage, so that designs mention the file. +- Checking by program whether the file is out of date. The agents are reminded; nothing enforces it. +- Adding the file to the other projects by hand: each gets it with its next planned task that needs it.