From 17e626dfba901aa8fc71062009c8bf3e15a7866a Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 3 Sep 2026 02:44:41 +1000 Subject: [PATCH] feat(workflow): route arbitrary forge labels to workflows via playbook YAML Second slice of docs/prds/eda-playbook-engine.md, complementing the kind->workflow layer (WorkflowRoutingFile): the label vocabulary itself becomes playbook data. A label outside the closed bug/feature/bootstrap kind set (e.g. security) now dispatches to a registered workflow from an optional WorkflowLabelsFile, instead of falling through to triage. - LabelWorkflows + LoadLabelWorkflowsYAML/SetLabelWorkflows in internal/domain/workflow/routing.go, mirroring the kind layer's once-at-startup lifecycle. The closed Kind/NATS-subject set is untouched; the map only extends binding authority for labels the kind layer does not own. - Collision rule per design doc: a label owned by the kind set, an empty label, an empty workflow name, or a duplicate binding is a reported load failure (dropped, logged, error returned to the caller) -- the schema defines what is accepted; nothing is silently arbitrated by schema/version. - Route() precedence: explicit t.Workflow -> arbitrary-label binding -> kind binding -> triage -> implement -> default. - Config: WorkflowLabelsFile (workflow_labels_file), wired at boot alongside WorkflowRoutingFile; documented in config.example.toml. - PRD: records this slice's decisions (single-file shape, collision rule, precedence) so later slices stay anchored. --- config.example.toml | 2 + docs/prds/eda-playbook-engine.md | 24 +++++ internal/app/archied/bootstrap.go | 7 ++ internal/config/config.go | 8 ++ internal/domain/workflow/routing.go | 79 +++++++++++++++ internal/domain/workflow/routing_test.go | 124 +++++++++++++++++++++++ 6 files changed, 244 insertions(+) diff --git a/config.example.toml b/config.example.toml index b79af450d..281e523e8 100644 --- a/config.example.toml +++ b/config.example.toml @@ -17,6 +17,8 @@ # skills_dir = "~/.local/share/archie/skills" # SKILL.md search path; defaults under work_dir when unset # plugin_dir = "~/.local/share/archie/plugins" # daemon plugin manifests; unset means no plugins are loaded +# workflow_routing_file = "~/.local/share/archie/workflow-routing.yaml" # kind->workflow rebinding (bug/feature/bootstrap) +# workflow_labels_file = "~/.local/share/archie/workflow-labels.yaml" # arbitrary forge label -> workflow (EDA playbook slice 2) poll_interval = "60s" label = "archie" diff --git a/docs/prds/eda-playbook-engine.md b/docs/prds/eda-playbook-engine.md index 4cc76c937..53492b2e4 100644 --- a/docs/prds/eda-playbook-engine.md +++ b/docs/prds/eda-playbook-engine.md @@ -238,6 +238,30 @@ before Channel/Forge actions or multi-action playbooks ship. `internal/config` / `configuration.Document`, and whether it's one directory or a list (mirroring `SkillsDir`'s shape) -- follow existing config precedent, not invented fresh. + + **Status 2026-09-03: partially resolved.** The label-vocabulary slice + landed with a single-file shape (`workflow_labels_file`, mirroring + `workflow_routing_file` and `SkillsDir`'s single-path precedent) rather + than a directory, because it is the smallest useful case. A directory + (multiple playbooks, per-repo scoping) remains open and larger; the + single-file shape does not preclude it -- a future `workflow_dir` would + compose `workflow_labels_file`'s role into a loader. + + Decisions recorded from the label-vocabulary slice (commit pending): + - Arbitrary labels bind to registered workflow names via + `LabelWorkflows` + `LoadLabelWorkflowsYAML`/`SetLabelWorkflows` + (`internal/domain/workflow/routing.go`). + - The closed `Kind`/NATS-subject set is untouched; the label map only + extends binding authority for labels the kind layer does not own. + - Collision rule (per Sam, 2026-09-03): a label already owned by the + kind set (bug/feature/bootstrap), an empty label, an empty workflow + name, or a duplicate binding is a reported load failure -- dropped + and logged, the error returned to the caller. Nothing is silently + arbitrated by schema/version. This is the "schema defines the + accepted message; anything else is the caller's fault" rule applied + to the label layer. + - Precedence in `Route()`: explicit `t.Workflow` → arbitrary-label + binding → kind binding → triage → implement → default. 3. **Trust boundary for Module Yaegi code.** The plugin engine rule's invariant 6 draws a line between operator-trusted in-process code and repository-supplied code that must run in a container. A user-authored diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index a4d8d499a..bafbe78ad 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -645,6 +645,13 @@ func (b *boot) loadWorkflows(ctx context.Context) error { return err } workflow.SetKindWorkflows(kindWorkflows) + + labelWorkflows, err := workflow.LoadLabelWorkflowsYAML(cfg.WorkflowLabelsFile) + if err != nil { + log.Error("workflow labels file load failed", "path", cfg.WorkflowLabelsFile, "err", err) + return err + } + workflow.SetLabelWorkflows(labelWorkflows) skillsBase := cfg.SkillsDir if skillsBase == "" { skillsBase = cfg.WorkDir diff --git a/internal/config/config.go b/internal/config/config.go index 13dfdfbfd..8c5ae09e2 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -439,6 +439,14 @@ type Config struct { // built-in bindings (bug->tdd, feature->feasibility, // bootstrap->bootstrap) are used unchanged. WorkflowRoutingFile string `toml:"workflow_routing_file" yaml:"workflow_routing_file"` + // WorkflowLabelsFile is an optional path to a YAML file binding forge + // issue labels outside the closed bug/feature/bootstrap kind set to + // registered workflows (e.g. "security" -> "security-review") -- the + // second slice of docs/prds/eda-playbook-engine.md. When empty, only + // the kind layer routes by label. A label already owned by the kind + // set, or a duplicate binding, is a load failure per the design doc's + // collision rule. + WorkflowLabelsFile string `toml:"workflow_labels_file" yaml:"workflow_labels_file"` // MaxRetries caps how many times a parked task is retried before // being permanently parked (status "dead"). Defaults to 3. MaxRetries int `toml:"max_retries" yaml:"max_retries"` diff --git a/internal/domain/workflow/routing.go b/internal/domain/workflow/routing.go index 8732a9c0e..192d282ef 100644 --- a/internal/domain/workflow/routing.go +++ b/internal/domain/workflow/routing.go @@ -3,6 +3,7 @@ package workflow import ( "fmt" "os" + "strings" "gopkg.in/yaml.v3" @@ -81,6 +82,20 @@ func LoadKindWorkflowsYAML(path string) (KindWorkflows, error) { // labels, trying each recognised kind in label order so a "bug,feature" task // still reaches feasibility when no tdd workflow is registered. func workflowForLabels(reg Registry, labels string) (Workflow, bool) { + // Arbitrary-label bindings first: a playbook-declared label is an + // explicit, load-time-error-checked signal, so it wins over the kind + // defaults (which cover only bug/feature/bootstrap). + if lb := activeLabelWorkflows; lb != nil { + for _, label := range workintake.SplitLabels(labels) { + name, ok := lb[label] + if !ok { + continue + } + if wf, ok := reg[name]; ok { + return wf, true + } + } + } kw := activeKindWorkflows if kw == nil { kw = defaultKindWorkflows @@ -96,3 +111,67 @@ func workflowForLabels(reg Registry, labels string) (Workflow, bool) { } return Workflow{}, false } + +// LabelWorkflows maps a forge issue label to the registered workflow name +// it prefers. This is the second slice of docs/prds/eda-playbook-engine.md: +// the label vocabulary itself -- not just the closed bug/feature/bootstrap +// kind set -- becomes playbook data. The closed Kind/NATS-subject set +// (workintake) is deliberately untouched; this map only extends binding +// authority for labels the kind layer does not own. +type LabelWorkflows map[string]string + +// activeLabelWorkflows is what workflowForLabels consults for arbitrary +// labels. Set once at daemon startup by SetLabelWorkflows; nil means "no +// arbitrary-label bindings" (there is no built-in default -- the closed +// kind set already owns bug/feature/bootstrap, and loading bindings for +// those is rejected as a collision), mirroring activeKindWorkflows' +// lifecycle. +var activeLabelWorkflows LabelWorkflows + +// SetLabelWorkflows overrides the label-to-workflow-name bindings Route() +// consults, e.g. from a file loaded by LoadLabelWorkflowsYAML. Passing nil +// restores kind-only routing. +func SetLabelWorkflows(lw LabelWorkflows) { + activeLabelWorkflows = lw +} + +// LoadLabelWorkflowsYAML reads a label-to-workflow-name binding file. An +// empty path returns (nil, nil) -- "no file configured" means "no +// arbitrary-label bindings", matching the kind layer's convention. +// +// A label already owned by the closed kind set (bug/feature/bootstrap) is a +// definition collision and returns an error: two authorities claiming one +// label is the caller's fault, reported not arbitrated. Empty labels or +// empty workflow names are likewise rejected -- the schema defines what is +// accepted, anything else is dropped-and-reported per the design doc. +func LoadLabelWorkflowsYAML(path string) (LabelWorkflows, error) { + if path == "" { + return nil, nil + } + data, err := os.ReadFile(path) + if err != nil { + return nil, fmt.Errorf("read label-workflows file %s: %w", path, err) + } + raw := map[string]string{} + if err := yaml.Unmarshal(data, &raw); err != nil { + return nil, fmt.Errorf("parse label-workflows file %s: %w", path, err) + } + lw := make(LabelWorkflows, len(raw)) + for label, name := range raw { + trimmed := strings.TrimSpace(label) + if trimmed == "" { + return nil, fmt.Errorf("label-workflows file %s: empty label is not a valid binding", path) + } + if name == "" { + return nil, fmt.Errorf("label-workflows file %s: label %q has no workflow name", path, trimmed) + } + if _, ok := defaultKindWorkflows[workintake.Kind(trimmed)]; ok { + return nil, fmt.Errorf("label-workflows file %s: label %q is already owned by the kind routing layer", path, trimmed) + } + if _, exists := lw[trimmed]; exists { + return nil, fmt.Errorf("label-workflows file %s: duplicate binding for label %q", path, trimmed) + } + lw[trimmed] = name + } + return lw, nil +} diff --git a/internal/domain/workflow/routing_test.go b/internal/domain/workflow/routing_test.go index eb3ae0df3..b4a979bde 100644 --- a/internal/domain/workflow/routing_test.go +++ b/internal/domain/workflow/routing_test.go @@ -1,6 +1,7 @@ package workflow import ( + "context" "os" "path/filepath" "testing" @@ -121,3 +122,126 @@ func writeFile(t *testing.T, path, content string) { t.Fatalf("write %s: %v", path, err) } } + +// ─── Label vocabulary layer (arbitrary labels → workflow) ─────────────── + +// TestRouteWithArbitraryLabelDispatch is the core of this slice: a forge +// label outside the closed bug/feature/bootstrap kind set (e.g. "security") +// routes to a registered workflow via the loaded LabelWorkflows map -- +// the label vocabulary becomes playbook data, not a Go literal, without +// touching the closed Kind/NATS-subject set. +func TestRouteWithArbitraryLabelDispatch(t *testing.T) { + SetLabelWorkflows(LabelWorkflows{"security": "security-review"}) + t.Cleanup(func() { SetLabelWorkflows(nil) }) + + task := &store.Task{Labels: "security"} + wf := Route(task, Registry{ + "implement": Implement(), + "security-review": Workflow{Name: "security-review", Stages: []Stage{{Name: "review", Run: func(_ context.Context, _ *TaskContext) error { return nil }}}}, + }) + if wf.Name != "security-review" { + t.Fatalf("Route() = %q, want %q (label dispatch not applied)", wf.Name, "security-review") + } +} + +// TestLoadLabelWorkflowsYAMLReadsBindings ensures a label→workflow file +// loads into a map Route() honours. +func TestLoadLabelWorkflowsYAMLReadsBindings(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "labels.yaml") + writeFile(t, path, "security: security-review\ndocs: docs-notify\n") + + lw, err := LoadLabelWorkflowsYAML(path) + if err != nil { + t.Fatalf("LoadLabelWorkflowsYAML() error = %v", err) + } + if lw["security"] != "security-review" || lw["docs"] != "docs-notify" { + t.Fatalf("LoadLabelWorkflowsYAML() = %#v, want both bindings", lw) + } +} + +// TestLoadLabelWorkflowsYAMLCollisionIsReported is the collision rule from +// the design doc: two bindings for the same label, or a label colliding +// with the closed kind set, is the caller's fault -- reported as an error, +// nothing silently wins by version or by declaration order. +func TestLoadLabelWorkflowsYAMLCollisionIsReported(t *testing.T) { + dir := t.TempDir() + + // Same label twice inside one file: neither declared with higher + // schema/version wins; the load fails. + path := filepath.Join(dir, "dup.yaml") + writeFile(t, path, "security: workflow-a\nsecurity: workflow-b\n") + if _, err := LoadLabelWorkflowsYAML(path); err == nil { + t.Fatal("LoadLabelWorkflowsYAML() error = nil, want collision error for duplicate label") + } + + // A label that the built-in kind set owns (bug) is itself a collision: + // KindForLabels already routes it; shadowing it here would be two + // authorities claiming one label. + path2 := filepath.Join(dir, "shadow.yaml") + writeFile(t, path2, "bug: custom-bug\n") + if _, err := LoadLabelWorkflowsYAML(path2); err == nil { + t.Fatal("LoadLabelWorkflowsYAML() error = nil, want error for label owned by kind set") + } +} + +// TestLoadLabelWorkflowsYAMLRejectsEmpties pins the schema gate: an empty +// label or empty workflow name is not an accepted message. +func TestLoadLabelWorkflowsYAMLRejectsEmpties(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "empty.yaml") + writeFile(t, path, "\"\": security-review\n") + if _, err := LoadLabelWorkflowsYAML(path); err == nil { + t.Fatal("LoadLabelWorkflowsYAML() error = nil, want error for empty label") + } + path2 := filepath.Join(dir, "empty-wf.yaml") + writeFile(t, path2, "security: \"\"\n") + if _, err := LoadLabelWorkflowsYAML(path2); err == nil { + t.Fatal("LoadLabelWorkflowsYAML() error = nil, want error for empty workflow name") + } +} + +// TestLoadLabelWorkflowsYAMLMissingFileReturnsNilNoError treats an unset +// playbook dir as "no label bindings", matching the kind layer's convention. +func TestLoadLabelWorkflowsYAMLMissingFileReturnsNilNoError(t *testing.T) { + lw, err := LoadLabelWorkflowsYAML("") + if err != nil { + t.Fatalf("LoadLabelWorkflowsYAML(\"\") error = %v, want nil", err) + } + if lw != nil { + t.Fatalf("LoadLabelWorkflowsYAML(\"\") = %#v, want nil", lw) + } +} + +// TestSetLabelWorkflowsNilRestoresDefaults pins that clearing the label map +// restores kind-only routing: an arbitrary label no longer routes. +func TestSetLabelWorkflowsNilRestoresDefaults(t *testing.T) { + SetLabelWorkflows(LabelWorkflows{"security": "security-review"}) + SetLabelWorkflows(nil) + + task := &store.Task{Labels: "security"} + wf := Route(task, Registry{"implement": Implement(), "security-review": Workflow{Name: "security-review", Stages: []Stage{{Name: "review", Run: func(_ context.Context, _ *TaskContext) error { return nil }}}}}) + if wf.Name != "implement" { + t.Fatalf("Route() = %q, want %q (label map not restored to empty)", wf.Name, "implement") + } +} + +// TestRoutePrefersArbitraryLabelOverKind pins precedence: for a task +// carrying both a kind label and an arbitrary label, the arbitrary-label +// binding (explicitly loaded) wins over the kind default. +func TestRoutePrefersArbitraryLabelOverKind(t *testing.T) { + SetLabelWorkflows(LabelWorkflows{"security": "security-review"}) + t.Cleanup(func() { SetLabelWorkflows(nil) }) + SetKindWorkflows(nil) // ensure defaults + t.Cleanup(func() { SetKindWorkflows(nil) }) + + task := &store.Task{Labels: "bug,security"} + wf := Route(task, Registry{ + "tdd": TDD(), + "implement": Implement(), + "security-review": Workflow{Name: "security-review", Stages: []Stage{{Name: "review", Run: func(_ context.Context, _ *TaskContext) error { return nil }}}}, + }) + if wf.Name != "security-review" { + t.Fatalf("Route() = %q, want %q (arbitrary label should beat kind default)", wf.Name, "security-review") + } +}