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.
This commit is contained in:
sam committed 2026-09-03 02:44:41 +10:00
1 parent 245f2ad0c0
commit 17e626dfba
6 files changed
+244

No files matched your search

+2
View File
@@ -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"
+24
View File
@@ -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
+7
View File
@@ -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
+8
View File
@@ -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"`
+79
View File
@@ -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
}
+124
View File
@@ -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")
}
}