From bafff557db126e259ab14960f787197c45ba5a5c Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 11 Nov 2026 09:32:28 -0700 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20workflow=20models:=20reclaim=20?= =?UTF-8?q?stale=20model=20labels=20on=20unbind/rebind?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The stage engine provisions a bound model's label vocabulary but never removed it: unbinding a repository or rebinding it to a model with a different label set left the old labels behind forever. ensureStageLabels now remembers, per repository, which model labels it provisioned (workflows/provisioned/__.json in the workflow store) and on a hash change or unbind deletes the ones the current binding no longer declares — only when the label was provisioned by the hive, is outside the built-in stage family, is worn by no open issue or PR (one search per label; a failed search keeps it) and workflow.label_gc (default true) allows. Kept labels stay in the record so a later pass retries them; every deletion is audited as workflow_label_removed. A repository that was never bound, or a hive without the workflow store wired, makes no extra call and keeps the pre-existing behaviour. Refs hivecommons/hive#17620 Signed-off-by: Andrew Anderson --- src/cmd/hive/stage_engine.go | 4 + src/pkg/config/config.go | 13 ++ .../dashboard/settings_parity_allowlist.txt | 1 + src/pkg/github/attribution.go | 4 + .../automerge/automerge_stage_labels.go | 15 +- .../automerge/automerge_stage_labels_gc.go | 182 +++++++++++++++ .../automerge_stage_labels_workflow_test.go | 221 ++++++++++++++++++ src/pkg/github/client.go | 12 + src/pkg/stageengine/reconciler.go | 15 +- src/pkg/workflowmodel/provisioned.go | 33 +++ src/pkg/workflowmodel/store/provisioned.go | 94 ++++++++ src/pkg/workflowmodel/store/store_test.go | 50 ++++ 12 files changed, 637 insertions(+), 7 deletions(-) create mode 100644 src/pkg/github/automerge/automerge_stage_labels_gc.go create mode 100644 src/pkg/workflowmodel/provisioned.go create mode 100644 src/pkg/workflowmodel/store/provisioned.go diff --git a/src/cmd/hive/stage_engine.go b/src/cmd/hive/stage_engine.go index 72d5f41066..6038b3da79 100644 --- a/src/cmd/hive/stage_engine.go +++ b/src/cmd/hive/stage_engine.go @@ -48,6 +48,10 @@ func stageEngineOptions(cfg *config.Config, logger *slog.Logger) *stageengine.Op Metrics: stageengine.DefaultCounters(), WorkflowFor: stageEngineWorkflowFor(cfg, wfstore.Open(wfstore.Root(cfg.Data.WorkflowsDir)), logger), } + if cfg != nil { + stageEngine.opts.WorkflowProvisioned = wfstore.Open(wfstore.Root(cfg.Data.WorkflowsDir)) + stageEngine.opts.WorkflowLabelGC = func() bool { return cfg.Workflow.LabelGCEnabled() } + } }) return stageEngine.opts } diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index a061c6a702..0e18cf591c 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -285,6 +285,19 @@ type Config struct { // WorkflowConfig is the `workflow:` block (hivecommons/hive#17620). type WorkflowConfig struct { Enabled bool `yaml:"enabled" json:"enabled"` + // LabelGC lets the stage engine delete a bound model's labels from a + // repository once the repository is unbound or rebound to a model that + // no longer declares them (RFC phase 4 follow-up). Only labels the hive + // itself provisioned, outside the built-in stage family and worn by no + // open issue or PR, are ever deleted; each deletion is audited as + // workflow_label_removed. nil means true; false leaves every label in + // place and logs what would have gone. + LabelGC *bool `yaml:"label_gc,omitempty" json:"label_gc,omitempty"` +} + +// LabelGCEnabled is the effective workflow.label_gc (default true). +func (c WorkflowConfig) LabelGCEnabled() bool { + return c.LabelGC == nil || *c.LabelGC } // UnmarshalYAML accepts the operator-facing agents.github_api_hourly_cap diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index d0844ab284..718fbbf15f 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -617,3 +617,4 @@ data.workflows_dir # workflow-model store root; deployment knob, no Settings con project.workflow_bindings[].name # set through the per-repo workflow select on Settings → Repos via PUT /api/workflows/bindings, not a leaf-path control (RFC #17620) project.workflow_bindings[].repo # see project.workflow_bindings[].name project.workflow_bindings[].version # see project.workflow_bindings[].name +workflow.label_gc # operator safety knob for model-label garbage collection on rebind; yaml-only, no Settings control planned (RFC #17620) diff --git a/src/pkg/github/attribution.go b/src/pkg/github/attribution.go index 2c0a457215..e5c067c4e1 100644 --- a/src/pkg/github/attribution.go +++ b/src/pkg/github/attribution.go @@ -57,6 +57,10 @@ const ( // the dashboard audit log: issue created → PR created → PR merged. Detail // carries path= naming which hive path merged it (see PRAuditPath*). AuditActionPRMerged = "pr_merged" + // AuditActionWorkflowLabelRemoved records a workflow model's stale + // label deleted from a repository on unbind/rebind + // (hivecommons/hive#17620). + AuditActionWorkflowLabelRemoved = "workflow_label_removed" // AuditActionPRClosed is the audit action recorded when the hive closes a // PR WITHOUT merging it: the issue-request watcher's close relay targeting // a pull request number. It is the "closed without merging" half of the diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index 1c067eb514..64458bb614 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -1653,14 +1653,18 @@ func (f *engineStatusForge) DeleteComment(ctx context.Context, id int64) error { // A repository bound to a workflow model (hivecommons/hive#17620, P4) also // gets that model's own label vocabulary (Profile.LabelDefs) created or // recoloured, memoised by the model's hash so a rebinding — or a new -// version of the bound model — re-provisions on the next pass. An unbound -// repository takes exactly the built-in path. +// version of the bound model — re-provisions on the next pass, and the +// labels a previous binding provisioned that the new one no longer +// declares are reclaimed under the safety rules in +// automerge_stage_labels_gc.go. An unbound repository that was never +// bound takes exactly the built-in path. func (c *Engine) ensureStageLabels(ctx context.Context, owner, repo string, tracker *StageTracker, kinds authorkind.Names) error { full := strings.ToLower(owner + "/" + repo) var model []workflowmodel.LabelDef modelHash := "" - if p := c.workflowProfile(owner, repo); p != nil { - model, modelHash = p.LabelDefs(stagelabels.StageColor), p.Hash + profile := c.workflowProfile(owner, repo) + if profile != nil { + model, modelHash = profile.LabelDefs(stagelabels.StageColor), profile.Hash } tracker.mu.Lock() done := tracker.ensured[full] && tracker.ensuredWorkflow[full] == modelHash @@ -1733,6 +1737,9 @@ func (c *Engine) ensureStageLabels(ctx context.Context, owner, repo string, trac return err } } + // Remember what the model owns here and reclaim what a previous + // binding left behind (automerge_stage_labels_gc.go). + c.reconcileWorkflowLabels(ctx, owner, repo, profile, model, existing, kinds) tracker.mu.Lock() tracker.ensured[full] = true if tracker.ensuredWorkflow == nil { diff --git a/src/pkg/github/automerge/automerge_stage_labels_gc.go b/src/pkg/github/automerge/automerge_stage_labels_gc.go new file mode 100644 index 0000000000..d0d9747ea4 --- /dev/null +++ b/src/pkg/github/automerge/automerge_stage_labels_gc.go @@ -0,0 +1,182 @@ +package automerge + +import ( + "context" + "fmt" + "net/http" + "strings" + + gh "github.com/google/go-github/v72/github" + + "github.com/hivecommons/hive/pkg/authorkind" + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// Model-label garbage collection (hivecommons/hive#17620, RFC phase 4 +// follow-up). ensureStageLabels creates a bound model's label vocabulary in +// the repository; this file remembers what it created and, when the +// repository is unbound or rebound to a model with a different label set, +// deletes the labels that went stale — and only those: +// +// - the label is in the repository's provisioned record, i.e. this hive +// created (or adopted by recolouring) it for a model; a label the +// repository had on its own is never touched; +// - it is not in the built-in stage family (stagelabels.LabelDefsFor and +// the retired spellings in stagelabels.Renames); +// - no open issue or PR wears it (one search per label; a failed search +// keeps the label); +// - workflow.label_gc is on (stageengine.Options.WorkflowLabelGC). +// +// A label kept for any of these reasons stays in the record so a later +// rebinding retries it. Every deletion is audited as +// AuditActionWorkflowLabelRemoved through the transport. With no +// ProvisionedStore wired nothing is remembered and nothing is deleted, so +// an unbound repository on a hive without the workflow store sees no +// change at all. + +// workflowLabelAuditor is the optional Transport hook that records one +// model-label deletion in the audit log (hgithub.Client implements it). +type workflowLabelAuditor interface { + RecordWorkflowLabelRemoved(repo, label, model string) +} + +// workflowLabelGCOutcome is what one reconcile pass did, for tests and +// the log line. +type workflowLabelGCOutcome struct { + Removed []string + Kept []string +} + +// workflowProvisionedStore is the per-repository label memory, or nil. +func (c *Engine) workflowProvisionedStore() workflowmodel.ProvisionedStore { + if c == nil || c.stageEngine == nil { + return nil + } + return c.stageEngine.WorkflowProvisioned +} + +// workflowLabelGCEnabled is the live workflow.label_gc (default true). +func (c *Engine) workflowLabelGCEnabled() bool { + if c == nil || c.stageEngine == nil || c.stageEngine.WorkflowLabelGC == nil { + return true + } + return c.stageEngine.WorkflowLabelGC() +} + +// reconcileWorkflowLabels runs after the model's labels are provisioned: +// it diffs the repository's provisioned record against the current +// binding (p and its model label defs), deletes what is stale and safe to +// delete, and rewrites the record. existing is the live label list +// ensureStageLabels fetched (lower-cased name → label) and is updated in +// place. Errors are logged, never returned: provisioning already +// succeeded and a failed clean-up must not stop the stage pass. +func (c *Engine) reconcileWorkflowLabels(ctx context.Context, owner, repo string, p *workflowmodel.Profile, model []workflowmodel.LabelDef, existing map[string]*gh.Label, kinds authorkind.Names) workflowLabelGCOutcome { + var out workflowLabelGCOutcome + store := c.workflowProvisionedStore() + if store == nil { + return out + } + full := strings.ToLower(owner + "/" + repo) + prev, err := store.LoadProvisioned(full) + if err != nil { + c.warn("workflow label memory unreadable; model labels left in place", "repo", full, "err", err) + return out + } + if prev == nil && p == nil { + return out + } + current := map[string]bool{} + keep := make([]string, 0, len(model)) + for _, def := range model { + current[strings.ToLower(def.Name)] = true + keep = append(keep, def.Name) + } + builtin := map[string]bool{} + for _, def := range stagelabels.LabelDefsFor(kinds) { + builtin[strings.ToLower(def.Name)] = true + } + for old, stage := range stagelabels.Renames { + builtin[strings.ToLower(old)] = true + builtin[strings.ToLower(stage.Label())] = true + } + modelKey := "unbound" + if p != nil { + modelKey = p.Name + "@" + p.Version + } + if prev != nil { + seen := map[string]bool{} + for _, name := range prev.Labels { + lower := strings.ToLower(name) + if current[lower] || builtin[lower] || seen[lower] { + continue + } + seen[lower] = true + live, present := existing[lower] + if !present { + continue + } + if reason := c.deleteStaleWorkflowLabel(ctx, owner, repo, live.GetName(), modelKey); reason != "" { + c.warn("stale workflow model label left in place", "repo", full, "label", live.GetName(), "workflow", modelKey, "reason", reason) + keep = append(keep, live.GetName()) + out.Kept = append(out.Kept, live.GetName()) + continue + } + delete(existing, lower) + out.Removed = append(out.Removed, live.GetName()) + } + } + if len(out.Removed) > 0 { + c.info("stale workflow model labels removed", "repo", full, "workflow", modelKey, "labels", strings.Join(out.Removed, ",")) + } + if p == nil && len(keep) == 0 { + if err := store.DeleteProvisioned(full); err != nil { + c.warn("workflow label memory not cleared", "repo", full, "err", err) + } + return out + } + rec := workflowmodel.ProvisionedLabels{Repo: full, Labels: keep, UpdatedAt: c.now()} + if p != nil { + rec.Name, rec.Version, rec.Hash = p.Name, p.Version, p.Hash + } + if err := store.SaveProvisioned(rec); err != nil { + c.warn("workflow label memory not written", "repo", full, "err", err) + } + return out +} + +// deleteStaleWorkflowLabel deletes name from the repository when the knob +// allows and nothing open wears it; it returns "" on deletion and the +// reason the label was kept otherwise. +func (c *Engine) deleteStaleWorkflowLabel(ctx context.Context, owner, repo, name, modelKey string) string { + if !c.workflowLabelGCEnabled() { + return "workflow.label_gc is off" + } + inUse, err := c.workflowLabelInUse(ctx, owner, repo, name) + if err != nil { + return "search failed: " + err.Error() + } + if inUse > 0 { + return fmt.Sprintf("worn by %d open item(s)", inUse) + } + if _, err := c.gh.Issues.DeleteLabel(ctx, owner, repo, name); err != nil && !isGitHubStatus(err, http.StatusNotFound) { + return "delete failed: " + err.Error() + } + if a, ok := c.transport.(workflowLabelAuditor); ok { + a.RecordWorkflowLabelRemoved(owner+"/"+repo, name, modelKey) + } + return "" +} + +// workflowLabelInUse counts the open issues and PRs wearing name. +func (c *Engine) workflowLabelInUse(ctx context.Context, owner, repo, name string) (int, error) { + q := fmt.Sprintf(`repo:%s/%s is:open label:"%s"`, owner, repo, strings.ReplaceAll(name, `"`, `\"`)) + res, _, err := c.gh.Search.Issues(ctx, q, &gh.SearchOptions{ListOptions: gh.ListOptions{PerPage: 1}}) + if err != nil { + return 0, err + } + if res == nil { + return 0, nil + } + return res.GetTotal(), nil +} diff --git a/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go b/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go index 943e275af4..ef0c3505e6 100644 --- a/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go +++ b/src/pkg/github/automerge/automerge_stage_labels_workflow_test.go @@ -3,8 +3,11 @@ package automerge import ( "context" "encoding/json" + "net/http" + "net/url" "os" "slices" + "strings" "testing" "time" @@ -14,6 +17,7 @@ import ( "github.com/hivecommons/hive/pkg/stagelabels" "github.com/hivecommons/hive/pkg/workflowmodel" "github.com/hivecommons/hive/pkg/workflowmodel/hivedefault" + wfstore "github.com/hivecommons/hive/pkg/workflowmodel/store" ) func workflowTestProfile(t *testing.T, labels ...workflowmodel.LabelEntry) *workflowmodel.Profile { @@ -148,3 +152,220 @@ func TestEnsureStageLabelsProvisionsBoundModelAndReprovisionsOnRebind(t *testing t.Fatal("unbind deleted a model label") } } + +// --- label garbage collection (RFC phase 4 follow-up) ------------------- + +// workflowGCAPI extends stageAPI with the two routes the collector uses: +// GET /search/issues (open items wearing a label, from inUse) and DELETE +// /repos/acme/widget/labels/. searchErr makes every search fail. +type workflowGCAPI struct { + inUse map[string]int + searchErr bool + deleted []string + searches []string +} + +func (g *workflowGCAPI) install(api *stageAPI) { + api.extra = func(w http.ResponseWriter, r *http.Request) bool { + switch { + case r.Method == http.MethodGet && r.URL.Path == "/search/issues": + q := r.URL.Query().Get("q") + g.searches = append(g.searches, q) + if g.searchErr { + w.WriteHeader(http.StatusBadGateway) + return true + } + total := 0 + for name, n := range g.inUse { + if strings.Contains(q, `label:"`+name+`"`) { + total = n + } + } + _ = json.NewEncoder(w).Encode(map[string]any{"total_count": total, "incomplete_results": false, "items": []any{}}) + return true + case r.Method == http.MethodDelete && strings.HasPrefix(r.URL.Path, "/repos/acme/widget/labels/"): + name, _ := url.PathUnescape(strings.TrimPrefix(r.URL.Path, "/repos/acme/widget/labels/")) + delete(api.labels, name) + g.deleted = append(g.deleted, name) + w.WriteHeader(http.StatusNoContent) + return true + } + return false + } +} + +// newWorkflowGCEngine is newWorkflowStageEngine with a provisioned-label +// store on a temp dir and the label_gc knob under test control. +func newWorkflowGCEngine(t *testing.T, apiURL string, lookup func(owner, repo string) *workflowmodel.Profile, store workflowmodel.ProvisionedStore, gc func() bool) (*Engine, *StageTracker, *[]hgithub.AuditRecord) { + t.Helper() + clock := &contributorLaneClock{at: time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC)} + client := hgithub.NewClient("token", "acme", []string{"widget"}, nil, apiURL) + audits := &[]hgithub.AuditRecord{} + client.SetAttributionAuditRecord(func(rec hgithub.AuditRecord) { *audits = append(*audits, rec) }) + tracker := NewStageTracker() + e := New(client, Options{ + Now: clock.now, + StageTracker: tracker, + StageEngine: &stageengine.Options{WorkflowFor: lookup, WorkflowProvisioned: store, WorkflowLabelGC: gc}, + }) + return e, tracker, audits +} + +func TestEnsureStageLabelsGCRemovesStaleKeepsInUseBuiltinAndForeign(t *testing.T) { + ctx := context.Background() + api := &stageAPI{labels: map[string]string{"docs/legacy": "000000"}} + gcAPI := &workflowGCAPI{inUse: map[string]int{"docs/030-drafting": 2}} + gcAPI.install(api) + srv := newStageAPI(t, api) + defer srv.Close() + store := wfstore.Open(t.TempDir()) + + v1 := workflowTestProfile(t, + workflowmodel.LabelEntry{Name: "docs/010-requested", State: "requested"}, + workflowmodel.LabelEntry{Name: "docs/020-analysing", State: "analysing"}, + workflowmodel.LabelEntry{Name: "docs/030-drafting", State: "drafting"}, + workflowmodel.LabelEntry{Name: stagelabels.NeedsDecision.Label(), State: "analysis-review"}, + ) + current := v1 + e, tracker, audits := newWorkflowGCEngine(t, srv.URL, func(string, string) *workflowmodel.Profile { return current }, store, nil) + + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + rec, err := store.LoadProvisioned("acme/widget") + if err != nil || rec == nil { + t.Fatalf("record after bind: %v %v", rec, err) + } + if rec.Name != v1.Name || rec.Hash != v1.Hash || !slices.Equal(rec.Labels, []string{"docs/010-requested", "docs/020-analysing", "docs/030-drafting", stagelabels.NeedsDecision.Label()}) { + t.Fatalf("record %+v", rec) + } + if len(gcAPI.deleted) != 0 || len(gcAPI.searches) != 0 { + t.Fatalf("first bind must not search or delete: %v %v", gcAPI.searches, gcAPI.deleted) + } + + // Rebind to a version that drops 020 (unused → removed), 030 (worn by + // two open items → kept) and the built-in 045 spelling (never deleted). + current = workflowTestProfile(t, workflowmodel.LabelEntry{Name: "docs/010-requested", State: "requested"}) + api.reset() + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if !slices.Equal(gcAPI.deleted, []string{"docs/020-analysing"}) { + t.Fatalf("deleted %v", gcAPI.deleted) + } + if _, ok := api.labels["docs/030-drafting"]; !ok { + t.Fatal("in-use label deleted") + } + if _, ok := api.labels[stagelabels.NeedsDecision.Label()]; !ok { + t.Fatal("built-in label deleted") + } + if _, ok := api.labels["docs/legacy"]; !ok { + t.Fatal("foreign label deleted") + } + if len(gcAPI.searches) != 2 { + t.Fatalf("searches %v (built-in and foreign labels must not be searched)", gcAPI.searches) + } + rec, _ = store.LoadProvisioned("acme/widget") + if rec == nil || rec.Hash != current.Hash || !slices.Equal(rec.Labels, []string{"docs/010-requested", "docs/030-drafting"}) { + t.Fatalf("record after rebind %+v", rec) + } + if len(*audits) != 1 || (*audits)[0].Action != hgithub.AuditActionWorkflowLabelRemoved || (*audits)[0].Repo != "acme/widget" || !strings.Contains((*audits)[0].Detail, "label=docs/020-analysing") || !strings.Contains((*audits)[0].Detail, "workflow="+current.Name+"@"+current.Version) { + t.Fatalf("audits %+v", *audits) + } + + // Unbind: 010 goes, 030 is still worn so the record survives with it. + current = nil + gcAPI.deleted = nil + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if !slices.Equal(gcAPI.deleted, []string{"docs/010-requested"}) { + t.Fatalf("unbind deleted %v", gcAPI.deleted) + } + rec, _ = store.LoadProvisioned("acme/widget") + if rec == nil || rec.Name != "" || !slices.Equal(rec.Labels, []string{"docs/030-drafting"}) { + t.Fatalf("record after unbind %+v", rec) + } + if !strings.Contains((*audits)[1].Detail, "workflow=unbound") { + t.Fatalf("unbind audit %+v", (*audits)[1]) + } + + // A new process (fresh tracker) on the unbound repo retries the kept + // label once nothing wears it, then drops the record. + delete(gcAPI.inUse, "docs/030-drafting") + gcAPI.deleted = nil + fresh := NewStageTracker() + if err := e.ensureStageLabels(ctx, "acme", "widget", fresh, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if !slices.Equal(gcAPI.deleted, []string{"docs/030-drafting"}) { + t.Fatalf("restart deleted %v", gcAPI.deleted) + } + if rec, _ = store.LoadProvisioned("acme/widget"); rec != nil { + t.Fatalf("record should be gone, got %+v", rec) + } + if _, ok := api.labels["docs/legacy"]; !ok || len(api.labels) != len(stagelabels.AllLabelDefs())+1 { + t.Fatalf("labels left: %v", api.labels) + } +} + +func TestEnsureStageLabelsGCHonoursKnobAndSearchFailure(t *testing.T) { + ctx := context.Background() + for name, tc := range map[string]struct { + gc bool + searchErr bool + }{ + "knob off": {gc: false}, + "search failed": {gc: true, searchErr: true}, + } { + t.Run(name, func(t *testing.T) { + api := &stageAPI{} + gcAPI := &workflowGCAPI{searchErr: tc.searchErr} + gcAPI.install(api) + srv := newStageAPI(t, api) + defer srv.Close() + store := wfstore.Open(t.TempDir()) + current := workflowTestProfile(t, workflowmodel.LabelEntry{Name: "docs/020-analysing", State: "analysing"}) + e, tracker, audits := newWorkflowGCEngine(t, srv.URL, func(string, string) *workflowmodel.Profile { return current }, store, func() bool { return tc.gc }) + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + current = nil + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if len(gcAPI.deleted) != 0 || len(*audits) != 0 { + t.Fatalf("deleted %v audits %v", gcAPI.deleted, *audits) + } + if _, ok := api.labels["docs/020-analysing"]; !ok { + t.Fatal("label deleted") + } + if tc.gc != (len(gcAPI.searches) == 1) { + t.Fatalf("knob off must not search: %v", gcAPI.searches) + } + rec, _ := store.LoadProvisioned("acme/widget") + if rec == nil || !slices.Equal(rec.Labels, []string{"docs/020-analysing"}) { + t.Fatalf("kept label must stay remembered: %+v", rec) + } + }) + } +} + +// Without a provisioned store nothing is remembered and nothing deleted — +// the pre-P4-follow-up behaviour TestEnsureStageLabelsProvisionsBoundModelAndReprovisionsOnRebind +// pins; an unbound repository with no record makes no extra call either. +func TestEnsureStageLabelsGCNoStoreOrRecordIsInert(t *testing.T) { + ctx := context.Background() + api := &stageAPI{} + gcAPI := &workflowGCAPI{} + gcAPI.install(api) + srv := newStageAPI(t, api) + defer srv.Close() + e, tracker, _ := newWorkflowGCEngine(t, srv.URL, func(string, string) *workflowmodel.Profile { return nil }, wfstore.Open(t.TempDir()), nil) + if err := e.ensureStageLabels(ctx, "acme", "widget", tracker, authorkind.DefaultNames); err != nil { + t.Fatal(err) + } + if len(gcAPI.searches)+len(gcAPI.deleted) != 0 || api.lists != 1 { + t.Fatalf("unbound repo touched GC routes: %v %v", gcAPI.searches, gcAPI.deleted) + } +} diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index a80e5a2557..5e655aadd1 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -4940,6 +4940,18 @@ func (c *Client) RecordPRMergedAudit(repo string, number int, method, sha, path c.clearMergeFailureAlertsAfterMerge(repo, number, method) } +// RecordWorkflowLabelRemoved records the deletion of a workflow model's +// stale label from repo (automerge's label garbage collection, +// hivecommons/hive#17620). model is the binding that made it stale +// (name@version) or "unbound". +func (c *Client) RecordWorkflowLabelRemoved(repo, label, model string) { + if c == nil { + return + } + c.recordWriteAudit(AuditActionWorkflowLabelRemoved, InvocationMeta{Agent: AttributionAgentGovernor}, + WriteTarget{Repo: repo}, "label", label, "workflow", model) +} + // RepoWorkBreakdown explains the raw open issue and PR totals for one // repository. Enumeration assigns every raw item to exactly one primary // bucket at the same choice point that determines whether it is actionable. diff --git a/src/pkg/stageengine/reconciler.go b/src/pkg/stageengine/reconciler.go index 9acbf0b32e..8c2d4981fe 100644 --- a/src/pkg/stageengine/reconciler.go +++ b/src/pkg/stageengine/reconciler.go @@ -53,9 +53,18 @@ type Options struct { // Workflow: Workflow is the engine-wide model, WorkflowFor the // per-repository override. hivecommons/hive#17620 (RFC phase 2). WorkflowFor func(owner, repo string) *workflowmodel.Profile - Now func() time.Time - Logger *slog.Logger - Metrics Metrics + // WorkflowProvisioned remembers, per repository, the model labels the + // label reconciler created, so a later pass can tell its own labels + // from the repository's. nil: nothing is remembered and no model label + // is ever deleted. hivecommons/hive#17620 (RFC phase 4 follow-up). + WorkflowProvisioned workflowmodel.ProvisionedStore + // WorkflowLabelGC, read on every pass, says whether a remembered model + // label the current binding no longer declares may be deleted from the + // repository (workflow.label_gc). nil means true. + WorkflowLabelGC func() bool + Now func() time.Time + Logger *slog.Logger + Metrics Metrics } // ErrNoWriter is returned by an enforce-mode Reconcile with no Writer. diff --git a/src/pkg/workflowmodel/provisioned.go b/src/pkg/workflowmodel/provisioned.go new file mode 100644 index 0000000000..a22f3581db --- /dev/null +++ b/src/pkg/workflowmodel/provisioned.go @@ -0,0 +1,33 @@ +package workflowmodel + +import "time" + +// ProvisionedLabels is what the stage engine remembers having created in +// one repository for a bound model (hivecommons/hive#17620, RFC phase 4 +// follow-up): the model's identity at the time and the label names it +// provisioned. A later pass — in this process or the next — diffs it +// against the current binding to find labels that are stale, and only a +// label named here is ever a candidate for deletion. +type ProvisionedLabels struct { + // Repo is the lower-cased owner/name. + Repo string `json:"repo"` + Name string `json:"name,omitempty"` + Version string `json:"version,omitempty"` + Hash string `json:"hash,omitempty"` + // Labels are the model labels the engine created or recoloured, in + // declaration order, plus any stale label a previous pass kept because + // it was still in use. + Labels []string `json:"labels"` + UpdatedAt time.Time `json:"updatedAt,omitzero"` +} + +// ProvisionedStore persists ProvisionedLabels per repository. The workflow +// store (pkg/workflowmodel/store) implements it on the data volume; the +// engine runs with nil when no store is wired and then never deletes. +type ProvisionedStore interface { + // LoadProvisioned returns the record for repo, or nil (no error) when + // none has been written. + LoadProvisioned(repo string) (*ProvisionedLabels, error) + SaveProvisioned(rec ProvisionedLabels) error + DeleteProvisioned(repo string) error +} diff --git a/src/pkg/workflowmodel/store/provisioned.go b/src/pkg/workflowmodel/store/provisioned.go new file mode 100644 index 0000000000..408406fe35 --- /dev/null +++ b/src/pkg/workflowmodel/store/provisioned.go @@ -0,0 +1,94 @@ +package store + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "regexp" + "strings" + + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// ProvisionedSubdir holds one record per repository of the model labels +// the stage engine created there (workflowmodel.ProvisionedLabels): +// +// workflows/provisioned/__.json +const ProvisionedSubdir = "provisioned" + +var provisionedFileRe = regexp.MustCompile(`[^a-z0-9._-]+`) + +// provisionedPath is the record's file for repo; "" when repo is not an +// owner/name the file name can carry. +func (s *Store) provisionedPath(repo string) string { + repo = strings.ToLower(strings.TrimSpace(repo)) + owner, name, ok := strings.Cut(repo, "/") + if !ok || owner == "" || name == "" { + return "" + } + file := provisionedFileRe.ReplaceAllString(owner, "-") + "__" + provisionedFileRe.ReplaceAllString(name, "-") + ".json" + return filepath.Join(s.dir(), ProvisionedSubdir, file) +} + +// LoadProvisioned implements workflowmodel.ProvisionedStore. +func (s *Store) LoadProvisioned(repo string) (*workflowmodel.ProvisionedLabels, error) { + path := s.provisionedPath(repo) + if path == "" { + return nil, fmt.Errorf("provisioned labels: repository %q is not owner/name", repo) + } + s.mu.Lock() + defer s.mu.Unlock() + b, err := os.ReadFile(path) + if errors.Is(err, os.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, err + } + var rec workflowmodel.ProvisionedLabels + if err := json.Unmarshal(b, &rec); err != nil { + return nil, fmt.Errorf("provisioned labels for %s: %w", repo, err) + } + return &rec, nil +} + +// SaveProvisioned implements workflowmodel.ProvisionedStore. +func (s *Store) SaveProvisioned(rec workflowmodel.ProvisionedLabels) error { + path := s.provisionedPath(rec.Repo) + if path == "" { + return fmt.Errorf("provisioned labels: repository %q is not owner/name", rec.Repo) + } + rec.Repo = strings.ToLower(strings.TrimSpace(rec.Repo)) + if rec.Labels == nil { + rec.Labels = []string{} + } + b, err := json.MarshalIndent(rec, "", " ") + if err != nil { + return err + } + s.mu.Lock() + defer s.mu.Unlock() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return err + } + return writeAtomic(path, b) +} + +// DeleteProvisioned implements workflowmodel.ProvisionedStore; a missing +// record is not an error. +func (s *Store) DeleteProvisioned(repo string) error { + path := s.provisionedPath(repo) + if path == "" { + return fmt.Errorf("provisioned labels: repository %q is not owner/name", repo) + } + s.mu.Lock() + defer s.mu.Unlock() + if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) { + return err + } + return nil +} + +var _ workflowmodel.ProvisionedStore = (*Store)(nil) diff --git a/src/pkg/workflowmodel/store/store_test.go b/src/pkg/workflowmodel/store/store_test.go index 21b011da6b..64bf4db2a0 100644 --- a/src/pkg/workflowmodel/store/store_test.go +++ b/src/pkg/workflowmodel/store/store_test.go @@ -280,3 +280,53 @@ func TestNextVersion(t *testing.T) { t.Fatalf("builtin: %q %v", v, err) } } + +func TestProvisionedLabelsRoundTrip(t *testing.T) { + s := Open(t.TempDir()) + if rec, err := s.LoadProvisioned("Acme/Widget"); err != nil || rec != nil { + t.Fatalf("missing record: %v %v", rec, err) + } + if err := s.DeleteProvisioned("acme/widget"); err != nil { + t.Fatalf("delete missing: %v", err) + } + in := workflowmodel.ProvisionedLabels{Repo: "Acme/Widget", Name: "techdocs", Version: "1", Hash: "h", Labels: []string{"docs/010-requested"}, UpdatedAt: time.Date(2026, 11, 11, 9, 0, 0, 0, time.UTC)} + if err := s.SaveProvisioned(in); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(filepath.Join(s.dir(), ProvisionedSubdir, "acme__widget.json")); err != nil { + t.Fatal(err) + } + rec, err := s.LoadProvisioned("acme/widget") + if err != nil || rec == nil || rec.Repo != "acme/widget" || rec.Name != "techdocs" || rec.Hash != "h" || len(rec.Labels) != 1 || !rec.UpdatedAt.Equal(in.UpdatedAt) { + t.Fatalf("round trip: %+v %v", rec, err) + } + if err := s.SaveProvisioned(workflowmodel.ProvisionedLabels{Repo: "acme/widget"}); err != nil { + t.Fatal(err) + } + if rec, _ = s.LoadProvisioned("acme/widget"); rec == nil || rec.Labels == nil || len(rec.Labels) != 0 { + t.Fatalf("empty labels must marshal as []: %+v", rec) + } + if err := s.DeleteProvisioned("acme/widget"); err != nil { + t.Fatal(err) + } + if rec, _ = s.LoadProvisioned("acme/widget"); rec != nil { + t.Fatalf("still present: %+v", rec) + } + for _, bad := range []string{"", "widget", "/widget", "acme/"} { + if _, err := s.LoadProvisioned(bad); err == nil { + t.Errorf("LoadProvisioned(%q) accepted", bad) + } + if err := s.SaveProvisioned(workflowmodel.ProvisionedLabels{Repo: bad}); err == nil { + t.Errorf("SaveProvisioned(%q) accepted", bad) + } + if err := s.DeleteProvisioned(bad); err == nil { + t.Errorf("DeleteProvisioned(%q) accepted", bad) + } + } + if err := os.WriteFile(filepath.Join(s.dir(), ProvisionedSubdir, "acme__broken.json"), []byte("{"), 0o644); err != nil { + t.Fatal(err) + } + if _, err := s.LoadProvisioned("acme/broken"); err == nil { + t.Fatal("corrupt record accepted") + } +} From 7e500e57f92c43b50f40a64a56c1e933741c127f Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 11 Nov 2026 09:59:08 -0700 Subject: [PATCH 2/4] =?UTF-8?q?=E2=9C=A8=20workflow=20models:=20offer=20mo?= =?UTF-8?q?del-defined=20replies=20as=20human-gate=20verbs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A bound workflow model declares `replies` per state — the verbs a human may answer a gate with. Until now the compiler kept them but nothing offered or accepted them; the Activity Monitor pill and `/hive` comments only knew the built-in approve/decision/hold family. Now, for a repository bound to a non-default model: - `workflowmodel.Profile.RepliesForNumber` / `ReplyForNumber` resolve the verbs for the item's current stage number and the effect of each (the transition's `on` event, the target state, and the label `labels.entries` maps to that state, if any). - The `/hive` comment parser (`parseUnparkCommandFor`) tries the model's verbs first — multi-word, case-insensitive, trailing punctuation trimmed — and the sweep answers a parked issue with `applyIssueModelReply`: parking labels cleared as for approve, the mapped label applied (audited `hive_label_applied` with the reply), and one comment that keeps the `Decision:` round-trip intact and says what the model did with the reply. Answered replies are watermarks. Repositories with no binding go through exactly the old parser. - The tracker payload's `workflows.repos[].replies` carries the verbs per stage number; `stageTrackerHumanGateVerbs` appends them after the built-ins (deduped by label) as `wf:` actions, which POST `{"decision":"model-reply","reply":…}` to the item decision endpoint. The endpoint validates the verb against the bound model and audits `repo_item_decision_model_reply`. hive-default's block and the pill on unbound repositories are unchanged. - The issue-unpark sweep in cmd/hive gets the stage engine's `WorkflowFor` resolver so comment replies see the same binding the labeller does. Model replies are accepted on parked issues only; PR-state replies are left for a follow-up. Refs hivecommons/hive#17620 Signed-off-by: Andrew Anderson --- src/cmd/hive/main_sweeps.go | 8 + src/pkg/dashboard/api_repo_item_decision.go | 60 ++++- src/pkg/dashboard/stage_tracker_workflows.go | 45 +++- .../stage_tracker_workflows_replies_test.go | 182 +++++++++++++ .../static-src/js/tracker-actions.js | 19 ++ .../static-src/js/tracker-human-gate.js | 23 +- .../static-src/js/tracker-workflows.js | 20 ++ src/pkg/dashboard/static/index.html | 62 ++++- src/pkg/github/issue_model_reply.go | 200 ++++++++++++++ src/pkg/github/issue_model_reply_test.go | 244 ++++++++++++++++++ src/pkg/github/issue_unpark_command.go | 56 +++- src/pkg/github/pr_unpark_decision.go | 2 +- src/pkg/workflowmodel/compile.go | 4 + src/pkg/workflowmodel/replies.go | 179 +++++++++++++ src/pkg/workflowmodel/replies_test.go | 99 +++++++ 15 files changed, 1180 insertions(+), 23 deletions(-) create mode 100644 src/pkg/dashboard/stage_tracker_workflows_replies_test.go create mode 100644 src/pkg/github/issue_model_reply.go create mode 100644 src/pkg/github/issue_model_reply_test.go create mode 100644 src/pkg/workflowmodel/replies.go create mode 100644 src/pkg/workflowmodel/replies_test.go diff --git a/src/cmd/hive/main_sweeps.go b/src/cmd/hive/main_sweeps.go index 35f0474ab3..e3023e49e5 100644 --- a/src/cmd/hive/main_sweeps.go +++ b/src/cmd/hive/main_sweeps.go @@ -31,6 +31,7 @@ import ( "github.com/hivecommons/hive/pkg/stageengine/prstage" "github.com/hivecommons/hive/pkg/stagelabels" "github.com/hivecommons/hive/pkg/tracing" + "github.com/hivecommons/hive/pkg/workflowmodel" "github.com/hivecommons/hive/pkg/worksource" "go.opentelemetry.io/otel/attribute" ) @@ -1491,9 +1492,16 @@ func runIssueUnparkSweepIfDue(ctx context.Context, ghClient *github.Client, cfg approveOpts.TrustedBotSkipReview = func() bool { return cfg.AutoMerge.TrustedBotSkipsReview() } } approveEngine := automerge.New(ghClient, approveOpts) + // A bound workflow model's replies are accepted as `/hive ` + // (hivecommons/hive#17620); unbound repositories see no change. + var workflowFor func(owner, repo string) *workflowmodel.Profile + if cfg != nil { + workflowFor = stageEngineOptions(cfg, logger).WorkflowFor + } result, err := ghClient.SweepIssueUnparkCommands(ctx, github.IssueUnparkSweepOptions{ PRApproveReply: approveEngine.PRApproveReply, MaxActions: github.DefaultIssueUnparkSweepMaxActions, + WorkflowFor: workflowFor, // cfg is nil only in tests; nil leaves every repo on the default path. LabelDriven: func(repo string) bool { return cfg.RepoLabelDriven(repo) }, LabelApproval: labelApprovalPolicyResolver(cfg), diff --git a/src/pkg/dashboard/api_repo_item_decision.go b/src/pkg/dashboard/api_repo_item_decision.go index c6a7026252..815b23a052 100644 --- a/src/pkg/dashboard/api_repo_item_decision.go +++ b/src/pkg/dashboard/api_repo_item_decision.go @@ -85,16 +85,23 @@ const ( // superseding PR (hivecommons/hive#15136). It queues the same adoption // the Adopt decision does; it is never implied by an Approve. repoItemDecisionReauthor = "re-author" + // model-reply records one of the human-gate replies the repository's + // bound workflow model declares for the issue's current state + // (hivecommons/hive#17620, RFC phase 4): the verb rides in Reply and is + // recorded as `/hive `; the model's mapped label, if any, is + // applied. Refused on unbound repositories. + repoItemDecisionModelReply = "model-reply" repoItemDecisionMaxBody = 16 << 10 repoItemDecisionMaxComment = 4000 - auditRepoItemDecisionApprove = "repo_item_decision_approve" - auditRepoItemDecisionDirection = "repo_item_decision_direction" - auditRepoItemDecisionClose = "repo_item_decision_close" - auditRepoItemDecisionAdopt = "repo_item_decision_adopt" - auditRepoItemDecisionMerge = "repo_item_decision_merge" - auditRepoItemDecisionQueue = "repo_item_decision_queue_merge" + auditRepoItemDecisionApprove = "repo_item_decision_approve" + auditRepoItemDecisionDirection = "repo_item_decision_direction" + auditRepoItemDecisionModelReply = "repo_item_decision_model_reply" + auditRepoItemDecisionClose = "repo_item_decision_close" + auditRepoItemDecisionAdopt = "repo_item_decision_adopt" + auditRepoItemDecisionMerge = "repo_item_decision_merge" + auditRepoItemDecisionQueue = "repo_item_decision_queue_merge" // repoItemDecisionAdoptMarker opens the attributed note an Adopt // decision leaves on the PR. @@ -125,6 +132,8 @@ type repoItemDecisionRequest struct { Force bool `json:"force,omitempty"` // To with decision "reroute" is the target clanker's login, or "any". To string `json:"to,omitempty"` + // Reply with decision "model-reply" is the workflow model's verb. + Reply string `json:"reply,omitempty"` } // parseRepoItemSupersededBy resolves a "superseded by" reference the way an @@ -266,6 +275,10 @@ func repoItemDecisionResultWith(repoFull string, number int, itemType, decision, out.Outcome = "`/hive approve` recorded; parking labels lifted, `" + label + "` applied." out.Next = "The hive un-parks the issue and carries on; nothing is merged." } + case repoItemDecisionModelReply: + out.Action = rowActionDirected + out.Outcome = "Workflow reply recorded as `/hive " + strings.TrimSuffix(strings.TrimSpace(comment), ".") + "`; parking labels lifted, `" + label + "` applied." + out.Next = "The hive applies the label the model maps to this reply, if any, and carries on; nothing is merged." case repoItemDecisionDirection: out.Action = rowActionDirected out.Outcome = "Direction recorded as `/hive decision`: " + strings.TrimSuffix(strings.TrimSpace(comment), ".") + "." @@ -518,6 +531,39 @@ func (s *Server) handleRepoItemDecision(w http.ResponseWriter, r *http.Request) s.audit.LogRecord(user, auditRepoItemDecisionClose, auditDetail("repo", repoFull, "number", numStr, "type", itemType, "reason", verb, "superseded_by", supersededBy), "", repoFull, number) jsonResponse(w, repoItemDecisionResponse{OK: true, Repo: repoFull, Number: number, Decision: decision, Status: "closed", Label: label, Result: repoItemDecisionResult(repoFull, number, itemType, decision, comment, supersededBy, label, nil)}) + case repoItemDecisionModelReply: + verb := strings.TrimSpace(body.Reply) + if verb == "" { + jsonError(w, "a model reply needs the verb", http.StatusBadRequest) + return + } + if itemType == "pr" { + jsonError(w, "model replies are recorded on issues only", http.StatusBadRequest) + return + } + profile := s.workflowProfileForRepo(repoFull) + if profile == nil { + jsonError(w, "repository is not bound to a workflow model", http.StatusConflict) + return + } + event, err := gh.RecordOperatorIssueModelReply(ctx, repoFull, number, user, verb, comment, profile) + switch { + case errors.Is(err, ghpkg.ErrUnknownModelReply): + jsonError(w, err.Error(), http.StatusConflict) + return + case errors.Is(err, ghpkg.ErrIssueNotParked): + jsonError(w, "issue is not waiting on a decision", http.StatusConflict) + return + case errors.Is(err, ghpkg.ErrDecisionTargetIsPR): + jsonError(w, "this is a pull request; model replies are recorded on issues only", http.StatusBadRequest) + return + case err != nil: + jsonError(w, err.Error(), http.StatusBadGateway) + return + } + s.audit.LogRecord(user, auditRepoItemDecisionModelReply, auditDetail("repo", repoFull, "number", numStr, "workflow", profile.Name+"@"+profile.Version, "reply", verb, "decision", event.Decision), "", repoFull, number) + jsonResponse(w, repoItemDecisionResponse{OK: true, Repo: repoFull, Number: number, Decision: decision, Status: "unparked", Label: ghpkg.HumanAckLabel, + Result: repoItemDecisionResult(repoFull, number, itemType, decision, event.Decision, "", ghpkg.HumanAckLabel, nil)}) case repoItemDecisionReroute: if itemType != "pr" { jsonError(w, "reroute applies to pull requests", http.StatusBadRequest) @@ -567,7 +613,7 @@ func (s *Server) handleRepoItemDecision(w http.ResponseWriter, r *http.Request) } s.handlePullRequestMergeDecision(ctx, w, repoFull, number, user, decision, comment) default: - jsonError(w, "unknown decision; want approve, direction, close-superseded, close-wontfix, close-read, close-issue, adopt, reroute, re-author, merge-now or queue-merge", http.StatusBadRequest) + jsonError(w, "unknown decision; want approve, direction, model-reply, close-superseded, close-wontfix, close-read, close-issue, adopt, reroute, re-author, merge-now or queue-merge", http.StatusBadRequest) } } diff --git a/src/pkg/dashboard/stage_tracker_workflows.go b/src/pkg/dashboard/stage_tracker_workflows.go index 3e0d593361..639739a670 100644 --- a/src/pkg/dashboard/stage_tracker_workflows.go +++ b/src/pkg/dashboard/stage_tracker_workflows.go @@ -2,6 +2,7 @@ package dashboard import ( "sort" + "strconv" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/workflowmodel" @@ -28,7 +29,13 @@ type StageTrackerWorkflow struct { Version string `json:"version"` Hash string `json:"hash,omitempty"` Columns []StageTrackerWorkflowColumn `json:"columns,omitempty"` - Error string `json:"error,omitempty"` + // Replies maps a stage number (as a string key, the JSON object key + // the SPA indexes by `item.stage`) to the human-gate reply verbs the + // model declares for the state at that number (hivecommons/hive#17620, + // RFC phase 4). The gate pill offers them after the built-in verbs; + // each posts `/hive `. Absent when the model declares none. + Replies map[string][]string `json:"replies,omitempty"` + Error string `json:"error,omitempty"` } // StageTrackerWorkflowColumn is a column with the stage numbers it anchors, @@ -59,9 +66,45 @@ func stageTrackerWorkflowBlock(p *workflowmodel.Profile) StageTrackerWorkflow { sort.Ints(col.Numbers) out.Columns = append(out.Columns, col) } + // hive-default's replies are dashboard action ids, not comment verbs; + // its block stays exactly as before. + for n, id := range p.StateOfNumber { + if p.Name == hivedefault.Name { + break + } + if verbs := p.RepliesForNumber(n); len(verbs) > 0 && id != "" { + if out.Replies == nil { + out.Replies = map[string][]string{} + } + out.Replies[strconv.Itoa(n)] = append([]string{}, verbs...) + } + } return out } +// workflowProfileForRepo is the compiled model the repository is bound to +// — nil when unbound, bound to hive-default, or when the binding does not +// resolve — so the dashboard applies exactly the vocabulary the stage +// engine does (hivecommons/hive#17620). +func (s *Server) workflowProfileForRepo(repoFull string) *workflowmodel.Profile { + if s == nil || s.deps == nil || s.deps.Config == nil || !s.deps.Config.Workflow.Enabled { + return nil + } + lookup := s.workflowProfileLookup() + if lookup == nil { + return nil + } + b, ok := s.deps.Config.WorkflowBindingFor(repoFull) + if !ok { + return nil + } + p, err := lookup(b.Name, b.Version) + if err != nil || p == nil || p.Name == hivedefault.Name { + return nil + } + return p +} + // stageTrackerWorkflows builds the block from the config's bindings; nil when // there are none. func stageTrackerWorkflows(cfg *config.Config, lookup workflowProfileLookup, qualify func(string) string) *StageTrackerWorkflows { diff --git a/src/pkg/dashboard/stage_tracker_workflows_replies_test.go b/src/pkg/dashboard/stage_tracker_workflows_replies_test.go new file mode 100644 index 0000000000..ac920d2056 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_workflows_replies_test.go @@ -0,0 +1,182 @@ +package dashboard + +import ( + "net/http" + "os/exec" + "strings" + "testing" + "time" + + wfstore "github.com/hivecommons/hive/pkg/workflowmodel/store" +) + +// The tracker's workflow block carries the model's human-gate replies per +// stage number (hivecommons/hive#17620, RFC phase 4); hive-default's block +// stays as it was. +func TestStageTrackerWorkflowBlockCarriesReplies(t *testing.T) { + s := workflowTestServer(t, true) + if rec := wfReq(s, http.MethodPost, "/api/workflows", techdocsModel(t), true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + if _, err := s.deps.Config.SetWorkflowBinding("repo1", "cncf-techdocs", "1"); err != nil { + t.Fatal(err) + } + blk := stageTrackerWorkflows(s.deps.Config, s.workflowProfileLookup(), func(r string) string { return "myorg/" + r }) + if blk == nil || blk.Default.Replies != nil { + t.Fatalf("hive-default must carry no comment verbs: %+v", blk) + } + td := blk.Repos["myorg/repo1"] + if got := strings.Join(td.Replies["45"], ","); got != "approve analysis,revise" { + t.Fatalf("replies[45] = %q (%+v)", got, td.Replies) + } + if got := strings.Join(td.Replies["20"], ","); got != "hand back" { + t.Fatalf("replies[20] = %q", got) + } + if _, ok := td.Replies["10"]; ok { + t.Fatalf("a state without replies must be absent: %+v", td.Replies) + } +} + +func TestWorkflowProfileForRepo(t *testing.T) { + s := workflowTestServer(t, true) + if rec := wfReq(s, http.MethodPost, "/api/workflows", techdocsModel(t), true); rec.Code != http.StatusCreated { + t.Fatal(rec.Body.String()) + } + if _, err := s.deps.Config.SetWorkflowBinding("repo1", "cncf-techdocs", "1"); err != nil { + t.Fatal(err) + } + if _, err := s.deps.Config.SetWorkflowBinding("repo2", "ghost", "1"); err != nil { + t.Fatal(err) + } + org := s.deps.Config.Project.Org + s.deps.Config.Workflow.Enabled = false + if s.workflowProfileForRepo(org+"/repo1") != nil { + t.Fatal("workflow.enabled=false must resolve nothing") + } + s.deps.Config.Workflow.Enabled = true + if p := s.workflowProfileForRepo(org + "/repo1"); p == nil || p.Name != "cncf-techdocs" { + t.Fatalf("bound repo: %+v", p) + } + for _, repo := range []string{org + "/repo2", org + "/unbound", ""} { + if p := s.workflowProfileForRepo(repo); p != nil { + t.Errorf("%q resolved %s", repo, p.Name) + } + } + s.deps.WorkflowStore = nil + if s.workflowProfileForRepo(org+"/repo1") != nil { + t.Fatal("no store must resolve nothing") + } +} + +// A model reply from the dashboard records `/hive ` on the parked +// issue and applies the label the model maps; unbound repositories and +// verbs the model does not offer are refused before anything is written. +func TestRepoItemDecisionModelReply(t *testing.T) { + mock := &repoItemDecisionMock{issueLabels: []string{"stage/045-needs-decision"}} + srv := newRepoItemDecisionServer(t, mock) + if w := postRepoItemDecision(t, srv, 7, "writer", `{"decision":"model-reply","reply":"revise"}`); w.Code != http.StatusConflict || !strings.Contains(w.Body.String(), "not bound") { + t.Fatalf("unbound: code=%d body=%s", w.Code, w.Body.String()) + } + if w := postRepoItemDecision(t, srv, 7, "writer", `{"decision":"model-reply"}`); w.Code != http.StatusBadRequest { + t.Fatalf("blank verb: code=%d", w.Code) + } + + store := wfstore.Open(t.TempDir()) + if _, err := store.Save(techdocsModel(t), "andy", time.Now()); err != nil { + t.Fatal(err) + } + srv.deps.WorkflowStore = store + srv.deps.Config.Workflow.Enabled = true + if _, err := srv.deps.Config.SetWorkflowBinding("testrepo", "cncf-techdocs", "1"); err != nil { + t.Fatal(err) + } + if w := postRepoItemDecision(t, srv, 7, "writer", `{"decision":"model-reply","reply":"ship it"}`); w.Code != http.StatusConflict { + t.Fatalf("unknown verb: code=%d body=%s", w.Code, w.Body.String()) + } + if w := postRepoItemDecision(t, srv, 8, "writer", `{"decision":"model-reply","reply":"revise","type":"pr"}`); w.Code != http.StatusBadRequest { + t.Fatalf("pr: code=%d body=%s", w.Code, w.Body.String()) + } + if len(mock.added)+len(mock.comments) != 0 { + t.Fatalf("refusals must write nothing: added=%v comments=%v", mock.added, mock.comments) + } + + w := postRepoItemDecision(t, srv, 7, "writer", `{"decision":"model-reply","reply":"Revise","comment":"section 2 is thin"}`) + if w.Code != http.StatusOK { + t.Fatalf("model reply: code=%d body=%s", w.Code, w.Body.String()) + } + body := w.Body.String() + if !strings.Contains(body, `"status":"unparked"`) || !strings.Contains(body, "Workflow reply recorded as `/hive revise: section 2 is thin`") { + t.Fatalf("response = %s", body) + } + added := strings.Join(mock.added, ",") + if !strings.Contains(added, "approved-direction") || !strings.Contains(added, "techdocs/analysis") { + t.Fatalf("expected the ack and the model's label applied, got %v", mock.added) + } + if len(mock.comments) != 1 || !strings.Contains(mock.comments[0], "Workflow reply `revise` moves the item from `analysis-review` to `analysing`; `techdocs/analysis` applied.") || !strings.Contains(mock.comments[0], "hive dashboard") { + t.Fatalf("comments = %v", mock.comments) + } + actions := strings.Join(decisionAuditActions(srv), ",") + if !strings.Contains(actions, auditRepoItemDecisionModelReply) { + t.Fatalf("audit = %s", actions) + } +} + +// The gate pill offers the model's verbs after the built-ins, each as a +// `wf:` action that posts a model-reply decision on the issue. +func TestStageTrackerHumanGateModelVerbsWiring(t *testing.T) { + html := indexHTML(t) + for _, want := range []string{ + `function stageTrackerWorkflowReplies(item, workflows)`, + `function stageTrackerHumanGateVerbs(reasons, item, modelVerbs)`, + `const verbs = stageTrackerHumanGateVerbs(reasons, shown, modelVerbs);`, + `body: { decision: 'model-reply', reply: modelVerb, comment: payload.comment || '', type } };`, + } { + if !strings.Contains(html, want) { + t.Errorf("index.html missing model-verb wiring %q", want) + } + } +} + +func TestStageTrackerHumanGateModelVerbsNode(t *testing.T) { + node, err := exec.LookPath("node") + if err != nil { + t.Skip("node not installed") + } + html := indexHTML(t) + script := `const assert = require('assert'); +const STAGE_TRACKER_GATE_VERBS = { decision: ['gate:decide', 'decide:approve', 'decide:delegate'], hold: ['release', 'decide:delegate'] }; +const STAGE_TRACKER_GATE_PR_ONLY = ['decide:approve', 'gate:request-changes']; +const STAGE_TRACKER_GATE_LABELS = { 'decide:approve': 'Approve', 'decide:delegate': 'Let hive decide', 'gate:decide': 'Decide…', release: 'Release hold' }; +const STAGE_TRACKER_GATE_APPROVE_AS_IS = 'Approve as-is'; +const STAGE_TRACKER_GATE_POSTS = {}; +const STAGE_TRACKER_GATE_MODEL_PREFIX = 'wf:'; +function stageTrackerGateIsPR(item) { return !!item && (item.via_pr ? 'pr' : item.kind) === 'pr'; } +` + jsFunc(t, html, "stageTrackerWorkflowOf") + jsFunc(t, html, "stageTrackerWorkflowReplies") + jsFunc(t, html, "stageTrackerWorkflowReplyLabel") + + jsFunc(t, html, "stageTrackerHumanGateVerbs") + jsFunc(t, html, "stageTrackerModelReplyVerb") + ` +const td = { name: 'cncf-techdocs', version: '1', columns: [{ id: 'a', label: 'A', states: ['analysis-review'], numbers: [45] }], replies: { '45': ['approve analysis', 'revise', 'decide', ' '], '20': ['hand back'] } }; +const def = { name: 'hive-default', version: '1', columns: [{ id: 'open', label: 'Open', states: ['open'], numbers: [] }], replies: { '45': ['decide:approve'] } }; +const workflows = { default: def, repos: { 'cncf/techdocs': td, 'cncf/plain': def } }; +const issue = { repo: 'cncf/techdocs', kind: 'issue', stage: 45 }; +assert.deepStrictEqual(stageTrackerWorkflowReplies(issue, workflows), ['approve analysis', 'revise', 'decide']); +assert.deepStrictEqual(stageTrackerWorkflowReplies({ repo: 'cncf/techdocs', kind: 'issue', stage: 10 }, workflows), [], 'no replies at this state'); +assert.deepStrictEqual(stageTrackerWorkflowReplies({ repo: 'cncf/plain', kind: 'issue', stage: 45 }, workflows), [], 'hive-default offers none'); +assert.deepStrictEqual(stageTrackerWorkflowReplies({ repo: 'cncf/other', kind: 'issue', stage: 45 }, workflows), [], 'unbound'); +assert.deepStrictEqual(stageTrackerWorkflowReplies({ repo: 'cncf/techdocs', kind: 'pr', stage: 45 }, workflows), [], 'PR rows take no model verb'); +assert.deepStrictEqual(stageTrackerWorkflowReplies(issue, null), []); + +const reasons = [{ key: 'decision', tip: 'q' }]; +const plain = stageTrackerHumanGateVerbs(reasons, issue); +assert.deepStrictEqual(plain.map(v => v.id), ['gate:decide', 'decide:delegate'], 'no model verbs → unchanged'); +const verbs = stageTrackerHumanGateVerbs(reasons, issue, stageTrackerWorkflowReplies(issue, workflows)); +assert.deepStrictEqual(verbs.map(v => v.id), ['gate:decide', 'decide:delegate', 'wf:approve analysis', 'wf:revise'], 'model verbs follow the built-ins; "decide" collides with Decide… and is dropped'); +assert.strictEqual(verbs[2].label, 'Approve analysis'); +assert.ok(verbs[2].posts.includes('/hive approve analysis'), verbs[2].posts); +assert.strictEqual(verbs[3].model, true); +assert.strictEqual(stageTrackerModelReplyVerb('wf:approve analysis'), 'approve analysis'); +assert.strictEqual(stageTrackerModelReplyVerb('decide:approve'), ''); +assert.strictEqual(stageTrackerWorkflowReplyLabel(''), ''); +` + if out, err := runNodeStdin(node, script); err != nil { + t.Fatalf("node model verbs fixture failed: %v\n%s", err, out) + } +} diff --git a/src/pkg/dashboard/static-src/js/tracker-actions.js b/src/pkg/dashboard/static-src/js/tracker-actions.js index 3525a85868..a2694bd76f 100644 --- a/src/pkg/dashboard/static-src/js/tracker-actions.js +++ b/src/pkg/dashboard/static-src/js/tracker-actions.js @@ -1318,9 +1318,16 @@ if (bar.innerHTML !== html) bar.innerHTML = html; } function stageTrackerActionLabel(id) { + const modelVerb = typeof stageTrackerModelReplyVerb === 'function' ? stageTrackerModelReplyVerb(id) : ''; + if (modelVerb) return typeof stageTrackerWorkflowReplyLabel === 'function' ? stageTrackerWorkflowReplyLabel(modelVerb) : modelVerb; const base = typeof stageTrackerActionBase === 'function' ? stageTrackerActionBase(id) : id; return STAGE_TRACKER_ACTION_LABELS[base] || id; } + // Pure: the model verb a `wf:` human-gate action carries + // (hivecommons/hive#17620, RFC phase 4), '' for any other id. + function stageTrackerModelReplyVerb(id) { + return String(id || '').indexOf('wf:') === 0 ? String(id).slice(3).trim() : ''; + } // Pure: which endpoint an action hits for one item. `once` marks a // hive-wide call made one time per batch. function stageTrackerActionRequest(item, id, payload) { @@ -1376,6 +1383,13 @@ if (id === 'gate:confirm-sentinel') { return { url: '/api/repos/' + seg + '/items/' + n + '/sentinel-confirm', body: { comment: payload.comment || '', type } }; } + // A workflow model's reply verb: recorded as "/hive " on the + // parked issue; the server checks the verb against the bound model. + const modelVerb = typeof stageTrackerModelReplyVerb === 'function' ? stageTrackerModelReplyVerb(id) : ''; + if (modelVerb) { + if (type !== 'issue') return null; + return { url: '/api/repos/' + seg + '/items/' + n + '/decision', body: { decision: 'model-reply', reply: modelVerb, comment: payload.comment || '', type } }; + } if (id.indexOf('decide:') === 0) { const body = { decision: id.slice('decide:'.length), comment: payload.comment || '', type }; if (payload.supersededBy) body.superseded_by = payload.supersededBy; @@ -2202,6 +2216,11 @@ const target = stageTrackerRerouteTargetOf(id) || STAGE_TRACKER_REROUTE_ANY; return (await stageTrackerAsk('decide:reroute', 'confirm', stageTrackerRerouteConfirm(refs, who, target, stageTrackerTakeoverOf(items[0])))) ? { to: target } : null; } + const verb = typeof stageTrackerModelReplyVerb === 'function' ? stageTrackerModelReplyVerb(id) : ''; + if (verb) { + const v = await stageTrackerAsk(id, 'prompt', { title: stageTrackerActionLabel(id) + ' — ' + refs, label: 'Record "/hive ' + verb + '" on ' + refs + ' as ' + who + '? The hive un-parks the issue and applies the label the workflow model maps to this reply, if any. Note (optional)', placeholder: 'e.g. keep the shorter outline', confirmLabel: 'Send' }); + return v == null ? null : { comment: v }; + } return {}; } // Pure: the Adopt now confirm — the consequence line is the message. diff --git a/src/pkg/dashboard/static-src/js/tracker-human-gate.js b/src/pkg/dashboard/static-src/js/tracker-human-gate.js index eb0d6f8471..6bab762a8a 100644 --- a/src/pkg/dashboard/static-src/js/tracker-human-gate.js +++ b/src/pkg/dashboard/static-src/js/tracker-human-gate.js @@ -107,17 +107,32 @@ out.sort((x, y) => STAGE_TRACKER_GATE_ORDER.indexOf(x.key) - STAGE_TRACKER_GATE_ORDER.indexOf(y.key)); return out; } + // A model reply's action id: `wf:` + the verb as the model declares it. + const STAGE_TRACKER_GATE_MODEL_PREFIX = 'wf:'; // Pure: the verbs for a set of reasons — the union in reason order, // de-duplicated, first label wins (so "Approve" on review + decision // reads "Approve", and "Approve as-is" when the decision stands alone). - function stageTrackerHumanGateVerbs(reasons, item) { + // modelVerbs are the bound workflow model's replies for the row's + // state (hivecommons/hive#17620, RFC phase 4): they follow the built-in + // verbs as `wf:`, each posting "/hive ", skipping any whose + // label a built-in verb already reads. + function stageTrackerHumanGateVerbs(reasons, item, modelVerbs) { const ids = []; // A row with no PR has no head to approve or send back; those verbs // belong to PR rows (or an issue drawn through its covering PR). const onPR = item == null || stageTrackerGateIsPR(item); (reasons || []).forEach(r => (STAGE_TRACKER_GATE_VERBS[r.key] || []).forEach(id => { if (ids.indexOf(id) < 0 && (onPR || STAGE_TRACKER_GATE_PR_ONLY.indexOf(id) < 0)) ids.push(id); })); const onlyDecision = (reasons || []).length && reasons.every(r => r.key === 'decision'); - return ids.map(id => ({ id, label: id === 'decide:approve' && onlyDecision ? STAGE_TRACKER_GATE_APPROVE_AS_IS : STAGE_TRACKER_GATE_LABELS[id] || id, posts: STAGE_TRACKER_GATE_POSTS[id] || '' })); + const out = ids.map(id => ({ id, label: id === 'decide:approve' && onlyDecision ? STAGE_TRACKER_GATE_APPROVE_AS_IS : STAGE_TRACKER_GATE_LABELS[id] || id, posts: STAGE_TRACKER_GATE_POSTS[id] || '' })); + const taken = out.map(v => String(v.label).replace(/…$/, '').toLowerCase()); + (Array.isArray(modelVerbs) ? modelVerbs : []).forEach(verb => { + const v = String(verb || '').trim(); + const id = STAGE_TRACKER_GATE_MODEL_PREFIX + v; + if (!v || out.some(x => x.id === id) || taken.indexOf(v.toLowerCase()) >= 0) return; + taken.push(v.toLowerCase()); + out.push({ id, label: typeof stageTrackerWorkflowReplyLabel === 'function' ? stageTrackerWorkflowReplyLabel(v) : v, posts: 'Posts "/hive ' + v + '" — a reply the repository\'s workflow model declares for this state; the hive applies the state\'s label when the model maps one.', model: true }); + }); + return out; } // Pure: the status segment's words — "Needs human · review, sentinel". function stageTrackerHumanGateStatusText(reasons) { @@ -182,7 +197,9 @@ if (passive) return typeof stageTrackerLeadPillHtml === 'function' ? stageTrackerLeadPillHtml(item, passive) : ''; // A gate owed on a PR drawn under this issue row renders on that sub-row. if (Array.isArray(subRows) && subRows.length && item.kind === 'issue' && !item.via_pr && !leads.length && subRows.some(s => stageTrackerHumanGateReasons(s).length)) return ''; - const verbs = stageTrackerHumanGateVerbs(reasons, shown); + const workflows = opts && opts.workflows !== undefined ? opts.workflows : (typeof _stageTracker !== 'undefined' && _stageTracker ? _stageTracker.workflows : null); + const modelVerbs = typeof stageTrackerWorkflowReplies === 'function' ? stageTrackerWorkflowReplies(shown, workflows) : []; + const verbs = stageTrackerHumanGateVerbs(reasons, shown, modelVerbs); const text = stageTrackerHumanGateStatusText(reasons); const tip = stageTrackerHumanGateTip(reasons); const ico = typeof stageTrackerIcon === 'function' ? stageTrackerIcon('human', 'ham-ico ham-mod-ico') : ''; diff --git a/src/pkg/dashboard/static-src/js/tracker-workflows.js b/src/pkg/dashboard/static-src/js/tracker-workflows.js index c472c85d30..03b8e6d24a 100644 --- a/src/pkg/dashboard/static-src/js/tracker-workflows.js +++ b/src/pkg/dashboard/static-src/js/tracker-workflows.js @@ -38,6 +38,26 @@ return cols.findIndex(c => Array.isArray(c.numbers) && c.numbers.indexOf(n) >= 0); } + // Pure: the reply verbs the bound model declares for the item's + // current state (RFC phase 4, `workflows.repos[repo].replies` keyed by + // stage number), in the model's order; [] for an unbound repository, a + // PR row (the dashboard records model replies on issues only), or a + // state without replies. + function stageTrackerWorkflowReplies(item, workflows) { + if (!item || item.kind === 'pr' || item.via_pr) return []; + const wf = stageTrackerWorkflowOf({ workflows }, item.repo); + if (!wf || !wf.replies) return []; + const list = wf.replies[String(Number(item.stage) || 0)]; + return Array.isArray(list) ? list.map(v => String(v || '').trim()).filter(Boolean) : []; + } + + // Pure: a model verb as the pill prints it — "approve analysis" → + // "Approve analysis". + function stageTrackerWorkflowReplyLabel(verb) { + const v = String(verb || '').trim(); + return v ? v.charAt(0).toUpperCase() + v.slice(1) : ''; + } + function stageTrackerWorkflowBadgeHtml(wf) { if (!wf) return ''; const key = `${wf.name}@${wf.version}`; diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index d8848b8653..d2eae70bbb 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -19665,6 +19665,26 @@

Where to get help

return cols.findIndex(c => Array.isArray(c.numbers) && c.numbers.indexOf(n) >= 0); } + // Pure: the reply verbs the bound model declares for the item's + // current state (RFC phase 4, `workflows.repos[repo].replies` keyed by + // stage number), in the model's order; [] for an unbound repository, a + // PR row (the dashboard records model replies on issues only), or a + // state without replies. + function stageTrackerWorkflowReplies(item, workflows) { + if (!item || item.kind === 'pr' || item.via_pr) return []; + const wf = stageTrackerWorkflowOf({ workflows }, item.repo); + if (!wf || !wf.replies) return []; + const list = wf.replies[String(Number(item.stage) || 0)]; + return Array.isArray(list) ? list.map(v => String(v || '').trim()).filter(Boolean) : []; + } + + // Pure: a model verb as the pill prints it — "approve analysis" → + // "Approve analysis". + function stageTrackerWorkflowReplyLabel(verb) { + const v = String(verb || '').trim(); + return v ? v.charAt(0).toUpperCase() + v.slice(1) : ''; + } + function stageTrackerWorkflowBadgeHtml(wf) { if (!wf) return ''; const key = `${wf.name}@${wf.version}`; @@ -24910,9 +24930,16 @@

All labels

if (bar.innerHTML !== html) bar.innerHTML = html; } function stageTrackerActionLabel(id) { + const modelVerb = typeof stageTrackerModelReplyVerb === 'function' ? stageTrackerModelReplyVerb(id) : ''; + if (modelVerb) return typeof stageTrackerWorkflowReplyLabel === 'function' ? stageTrackerWorkflowReplyLabel(modelVerb) : modelVerb; const base = typeof stageTrackerActionBase === 'function' ? stageTrackerActionBase(id) : id; return STAGE_TRACKER_ACTION_LABELS[base] || id; } + // Pure: the model verb a `wf:` human-gate action carries + // (hivecommons/hive#17620, RFC phase 4), '' for any other id. + function stageTrackerModelReplyVerb(id) { + return String(id || '').indexOf('wf:') === 0 ? String(id).slice(3).trim() : ''; + } // Pure: which endpoint an action hits for one item. `once` marks a // hive-wide call made one time per batch. function stageTrackerActionRequest(item, id, payload) { @@ -24968,6 +24995,13 @@

All labels

if (id === 'gate:confirm-sentinel') { return { url: '/api/repos/' + seg + '/items/' + n + '/sentinel-confirm', body: { comment: payload.comment || '', type } }; } + // A workflow model's reply verb: recorded as "/hive " on the + // parked issue; the server checks the verb against the bound model. + const modelVerb = typeof stageTrackerModelReplyVerb === 'function' ? stageTrackerModelReplyVerb(id) : ''; + if (modelVerb) { + if (type !== 'issue') return null; + return { url: '/api/repos/' + seg + '/items/' + n + '/decision', body: { decision: 'model-reply', reply: modelVerb, comment: payload.comment || '', type } }; + } if (id.indexOf('decide:') === 0) { const body = { decision: id.slice('decide:'.length), comment: payload.comment || '', type }; if (payload.supersededBy) body.superseded_by = payload.supersededBy; @@ -25794,6 +25828,11 @@

All labels

const target = stageTrackerRerouteTargetOf(id) || STAGE_TRACKER_REROUTE_ANY; return (await stageTrackerAsk('decide:reroute', 'confirm', stageTrackerRerouteConfirm(refs, who, target, stageTrackerTakeoverOf(items[0])))) ? { to: target } : null; } + const verb = typeof stageTrackerModelReplyVerb === 'function' ? stageTrackerModelReplyVerb(id) : ''; + if (verb) { + const v = await stageTrackerAsk(id, 'prompt', { title: stageTrackerActionLabel(id) + ' — ' + refs, label: 'Record "/hive ' + verb + '" on ' + refs + ' as ' + who + '? The hive un-parks the issue and applies the label the workflow model maps to this reply, if any. Note (optional)', placeholder: 'e.g. keep the shorter outline', confirmLabel: 'Send' }); + return v == null ? null : { comment: v }; + } return {}; } // Pure: the Adopt now confirm — the consequence line is the message. @@ -26571,17 +26610,32 @@

All labels

out.sort((x, y) => STAGE_TRACKER_GATE_ORDER.indexOf(x.key) - STAGE_TRACKER_GATE_ORDER.indexOf(y.key)); return out; } + // A model reply's action id: `wf:` + the verb as the model declares it. + const STAGE_TRACKER_GATE_MODEL_PREFIX = 'wf:'; // Pure: the verbs for a set of reasons — the union in reason order, // de-duplicated, first label wins (so "Approve" on review + decision // reads "Approve", and "Approve as-is" when the decision stands alone). - function stageTrackerHumanGateVerbs(reasons, item) { + // modelVerbs are the bound workflow model's replies for the row's + // state (hivecommons/hive#17620, RFC phase 4): they follow the built-in + // verbs as `wf:`, each posting "/hive ", skipping any whose + // label a built-in verb already reads. + function stageTrackerHumanGateVerbs(reasons, item, modelVerbs) { const ids = []; // A row with no PR has no head to approve or send back; those verbs // belong to PR rows (or an issue drawn through its covering PR). const onPR = item == null || stageTrackerGateIsPR(item); (reasons || []).forEach(r => (STAGE_TRACKER_GATE_VERBS[r.key] || []).forEach(id => { if (ids.indexOf(id) < 0 && (onPR || STAGE_TRACKER_GATE_PR_ONLY.indexOf(id) < 0)) ids.push(id); })); const onlyDecision = (reasons || []).length && reasons.every(r => r.key === 'decision'); - return ids.map(id => ({ id, label: id === 'decide:approve' && onlyDecision ? STAGE_TRACKER_GATE_APPROVE_AS_IS : STAGE_TRACKER_GATE_LABELS[id] || id, posts: STAGE_TRACKER_GATE_POSTS[id] || '' })); + const out = ids.map(id => ({ id, label: id === 'decide:approve' && onlyDecision ? STAGE_TRACKER_GATE_APPROVE_AS_IS : STAGE_TRACKER_GATE_LABELS[id] || id, posts: STAGE_TRACKER_GATE_POSTS[id] || '' })); + const taken = out.map(v => String(v.label).replace(/…$/, '').toLowerCase()); + (Array.isArray(modelVerbs) ? modelVerbs : []).forEach(verb => { + const v = String(verb || '').trim(); + const id = STAGE_TRACKER_GATE_MODEL_PREFIX + v; + if (!v || out.some(x => x.id === id) || taken.indexOf(v.toLowerCase()) >= 0) return; + taken.push(v.toLowerCase()); + out.push({ id, label: typeof stageTrackerWorkflowReplyLabel === 'function' ? stageTrackerWorkflowReplyLabel(v) : v, posts: 'Posts "/hive ' + v + '" — a reply the repository\'s workflow model declares for this state; the hive applies the state\'s label when the model maps one.', model: true }); + }); + return out; } // Pure: the status segment's words — "Needs human · review, sentinel". function stageTrackerHumanGateStatusText(reasons) { @@ -26646,7 +26700,9 @@

All labels

if (passive) return typeof stageTrackerLeadPillHtml === 'function' ? stageTrackerLeadPillHtml(item, passive) : ''; // A gate owed on a PR drawn under this issue row renders on that sub-row. if (Array.isArray(subRows) && subRows.length && item.kind === 'issue' && !item.via_pr && !leads.length && subRows.some(s => stageTrackerHumanGateReasons(s).length)) return ''; - const verbs = stageTrackerHumanGateVerbs(reasons, shown); + const workflows = opts && opts.workflows !== undefined ? opts.workflows : (typeof _stageTracker !== 'undefined' && _stageTracker ? _stageTracker.workflows : null); + const modelVerbs = typeof stageTrackerWorkflowReplies === 'function' ? stageTrackerWorkflowReplies(shown, workflows) : []; + const verbs = stageTrackerHumanGateVerbs(reasons, shown, modelVerbs); const text = stageTrackerHumanGateStatusText(reasons); const tip = stageTrackerHumanGateTip(reasons); const ico = typeof stageTrackerIcon === 'function' ? stageTrackerIcon('human', 'ham-ico ham-mod-ico') : ''; diff --git a/src/pkg/github/issue_model_reply.go b/src/pkg/github/issue_model_reply.go new file mode 100644 index 0000000000..1853557a56 --- /dev/null +++ b/src/pkg/github/issue_model_reply.go @@ -0,0 +1,200 @@ +package github + +import ( + "context" + "fmt" + "strings" + + gh "github.com/google/go-github/v72/github" + + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" + "github.com/hivecommons/hive/pkg/workflowmodel/hivedefault" +) + +// unparkCommandModelReply is `/hive ` where is one of the +// replies the repository's bound workflow model declares for the item's +// current state (hivecommons/hive#17620, RFC phase 4). It is only ever +// produced when a model is bound; on an unbound repository the same comment +// is an unknown command exactly as before. +const unparkCommandModelReply unparkCommandKind = "model-reply" + +// modelReplyVerbs returns the verbs a bound model offers for an item wearing +// labels, in declaration order; nil for the hive-default model, a profile +// that is not bound, or a state that declares no replies. The state is the +// built-in stage number the item currently carries — the model's state +// numbers are its stage numbers (stageengine.DeriveForRepo). +func modelReplyVerbs(profile *workflowmodel.Profile, labels []string) []string { + if profile == nil || profile.Name == hivedefault.Name { + return nil + } + return profile.RepliesForNumber(stagelabels.Current(labels).Number()) +} + +// parseUnparkCommandFor is parseUnparkCommand extended with a model's reply +// verbs. On a bound repository the model owns the vocabulary for its state: +// the longest verb whose words open the command line (case, `_`/`-`, +// spacing and trailing punctuation folded by workflowmodel.NormalizeReply) +// is the reply and what follows is the decision text; only then do the +// built-in commands apply. An empty verb list is exactly parseUnparkCommand, +// so an unbound repository parses every comment as before. +func parseUnparkCommandFor(body string, verbs []string) (unparkCommand, bool) { + if cmd, ok := parseModelReplyCommand(body, verbs); ok { + return cmd, true + } + return parseUnparkCommand(body) +} + +func parseModelReplyCommand(body string, verbs []string) (unparkCommand, bool) { + if len(verbs) == 0 { + return unparkCommand{}, false + } + line := firstNonEmptyLine(body) + if line == "" || strings.HasPrefix(line, ">") || strings.HasPrefix(line, "```") || strings.HasPrefix(line, "~~~") { + return unparkCommand{}, false + } + fields := strings.Fields(line) + if len(fields) < 2 || !strings.EqualFold(fields[0], unparkCommandPrefix) { + return unparkCommand{}, false + } + rest := fields[1:] + best, bestWords := "", 0 + for _, verb := range verbs { + want := workflowmodel.NormalizeReply(verb) + if want == "" { + continue + } + for k := 1; k <= len(rest) && k <= modelReplyMaxWords; k++ { + got := workflowmodel.NormalizeReply(strings.TrimRight(strings.Join(rest[:k], " "), ".:,;!")) + if got == want && k > bestWords { + best, bestWords = verb, k + } + } + } + if best == "" { + return unparkCommand{}, false + } + decision := strings.TrimSpace(strings.Join(rest[bestWords:], " ")) + return unparkCommand{Kind: unparkCommandModelReply, Verb: best, Decision: decision, Text: decisionText(body, decision)}, true +} + +// modelReplyMaxWords bounds how many words of a command line are tried +// against a verb; model replies are short imperatives. +const modelReplyMaxWords = 6 + +// applyIssueModelReply records a model reply on a parked issue: the park +// labels the hive added are cleared as for `/hive approve`, the label the +// model maps to the reply's transition (if any) is applied, and the reply is +// answered in one comment. source names where the reply came from for the +// comment ("" for a comment command). labels are the issue's labels as read. +func (c *Client) applyIssueModelReply(ctx context.Context, owner, repo string, number int, labels []string, actor string, eff workflowmodel.ReplyEffect, text string, commentID int64, source string) (IssueUnparkEvent, error) { + needsHuman := unparkNeedsHumanOutcome{} + if hasIssueNeedsHumanLabel(labels) { + needsHuman = c.needsHumanOutcome(ctx, owner, repo, number, nil) + } + if err := c.clearIssueParkingLabels(ctx, owner, repo, number, labels, actor, needsHuman.lift); err != nil { + return IssueUnparkEvent{}, err + } + applied := "" + if eff.Label != "" && !labelPresent(labels, eff.Label) { + if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{eff.Label}); err != nil { + return IssueUnparkEvent{}, fmt.Errorf("adding %s to %s/%s#%d: %w", eff.Label, owner, repo, number, err) + } + c.recordWriteAudit(AuditActionHiveLabelApplied, hiveWriteMeta(), + WriteTarget{Repo: owner + "/" + repo, Number: number}, "label", eff.Label, "reply", eff.Verb) + applied = eff.Label + } + decision := eff.Verb + if t := strings.TrimSpace(text); t != "" { + decision += ": " + t + } + body := renderModelReplyAccepted(actor, decision, eff, applied, hasIssueNeedsHumanLabel(labels), needsHuman) + if source != "" { + body += "\n\n_Recorded from " + source + "._" + } + if err := c.postUnparkReply(ctx, owner, repo, number, commentID, body); err != nil { + return IssueUnparkEvent{}, err + } + event := IssueUnparkEvent{Repo: owner + "/" + repo, Number: number, Actor: actor, Decision: decision} + if c.logger != nil { + c.logger.Info("issue un-parked by model reply", "repo", event.Repo, "issue", number, "actor", actor, "reply", eff.Verb, "to", eff.To, "label", applied) + } + return event, nil +} + +// renderModelReplyAccepted is the reply to a model verb. It leads with the +// same sentence as a built-in decision so the `Decision:` round-trip the +// decision history reads is unchanged, then says what the model did with it. +func renderModelReplyAccepted(actor, decision string, eff workflowmodel.ReplyEffect, applied string, needsHuman bool, outcome unparkNeedsHumanOutcome) string { + b := renderUnparkAcceptedReply(actor, decision, needsHuman, outcome) + var tail strings.Builder + fmt.Fprintf(&tail, "\n\nWorkflow reply `%s`", eff.Verb) + switch { + case eff.To != "" && applied != "": + fmt.Fprintf(&tail, " moves the item from `%s` to `%s`; `%s` applied.", eff.From, eff.To, applied) + case eff.To != "": + fmt.Fprintf(&tail, " moves the item from `%s` to `%s`; the model maps no label to that state, so the reply is recorded here only.", eff.From, eff.To) + default: + tail.WriteString(" is recorded; the model declares no transition for it.") + } + return b + tail.String() +} + +// RecordOperatorIssueModelReply is RecordOperatorIssueDecision for a model +// reply chosen in the dashboard (hivecommons/hive#17620): verb must be one +// of the replies profile declares for the issue's current state, else +// ErrUnknownModelReply. profile nil or hive-default is the same error — the +// dashboard offers model verbs only for bound repositories. +func (c *Client) RecordOperatorIssueModelReply(ctx context.Context, repo string, number int, actor, verb, text string, profile *workflowmodel.Profile) (IssueUnparkEvent, error) { + if c == nil || c.client == nil { + return IssueUnparkEvent{}, ErrNoGitHubClient + } + actor = strings.TrimSpace(actor) + if actor == "" { + return IssueUnparkEvent{}, fmt.Errorf("RecordOperatorIssueModelReply: actor is required") + } + owner, name := c.splitRepo(repo) + if err := validateRepoRef(owner, name); err != nil { + return IssueUnparkEvent{}, fmt.Errorf("RecordOperatorIssueModelReply: %w", err) + } + if number <= 0 { + return IssueUnparkEvent{}, fmt.Errorf("RecordOperatorIssueModelReply: issue number is required") + } + issue, _, err := c.client.Issues.Get(ctx, owner, name, number) + if err != nil { + return IssueUnparkEvent{}, fmt.Errorf("reading %s#%d before reply: %w", repo, number, err) + } + if issue.IsPullRequest() { + return IssueUnparkEvent{}, ErrDecisionTargetIsPR + } + labels := issueLabelNames(issue.Labels) + eff, ok := modelReplyEffect(profile, labels, verb) + if !ok { + return IssueUnparkEvent{}, ErrUnknownModelReply + } + if !hasIssueParkingLabel(labels) { + return IssueUnparkEvent{}, ErrIssueNotParked + } + return c.applyIssueModelReply(ctx, owner, name, number, labels, actor, eff, text, operatorDecisionMarkerID, "the hive dashboard") +} + +// modelReplyEffect resolves verb against the replies the model offers for +// the item's current state. +func modelReplyEffect(profile *workflowmodel.Profile, labels []string, verb string) (workflowmodel.ReplyEffect, bool) { + if len(modelReplyVerbs(profile, labels)) == 0 { + return workflowmodel.ReplyEffect{}, false + } + return profile.ReplyForNumber(stagelabels.Current(labels).Number(), verb) +} + +// ErrUnknownModelReply is returned when a reply verb is not one the bound +// model declares for the item's current state. +var ErrUnknownModelReply = fmt.Errorf("reply is not one the workflow model offers for this item") + +// issueModelReplyVerbs is modelReplyVerbs for a listed issue. +func issueModelReplyVerbs(profile *workflowmodel.Profile, issue *gh.Issue) []string { + if profile == nil || issue == nil { + return nil + } + return modelReplyVerbs(profile, issueLabelNames(issue.Labels)) +} diff --git a/src/pkg/github/issue_model_reply_test.go b/src/pkg/github/issue_model_reply_test.go new file mode 100644 index 0000000000..f5ab3898c6 --- /dev/null +++ b/src/pkg/github/issue_model_reply_test.go @@ -0,0 +1,244 @@ +package github + +import ( + "context" + "encoding/json" + "errors" + "os" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" + "github.com/hivecommons/hive/pkg/workflowmodel/hivedefault" +) + +// techdocsReplyProfile compiles the techdocs test model with a label mapped +// to draft-under-way, so `approve analysis` at analysis-review (045) both +// moves the item and applies a label while `revise` only applies the label +// its event observes. +func techdocsReplyProfile(t *testing.T) *workflowmodel.Profile { + t.Helper() + b, err := os.ReadFile("../workflowmodel/testdata/models/techdocs.json") + if err != nil { + t.Fatal(err) + } + var m workflowmodel.Model + if err := json.Unmarshal(b, &m); err != nil { + t.Fatal(err) + } + m.Spec.Labels = workflowmodel.LabelSet{Prefix: "docs", Entries: []workflowmodel.LabelEntry{{Name: "docs/040-draft-under-way", State: "draft-under-way"}}} + p, _, err := workflowmodel.Compile(&m) + if err != nil { + t.Fatal(err) + } + return p +} + +func modelParkedIssue(number int, comments ...unparkWireComment) unparkWireIssue { + issue := parkedIssue(number, comments...) + issue.Labels = []wireLabel{{Name: stagelabels.IssueNeedsDecision.Label()}, {Name: "needs-human"}} + return issue +} + +func TestParseUnparkCommandForModelVerbs(t *testing.T) { + verbs := []string{"approve analysis", "revise", "approve", ""} + cases := []struct { + body string + kind unparkCommandKind + verb, text string + ok bool + }{ + {"/hive Approve_Analysis", unparkCommandModelReply, "approve analysis", "", true}, + {"/hive approve-analysis looks right\n\n1. keep the table", unparkCommandModelReply, "approve analysis", "looks right\n\n1. keep the table", true}, + {" /HIVE revise: tighten section 2", unparkCommandModelReply, "revise", "tighten section 2", true}, + {"/hive approve", unparkCommandModelReply, "approve", "", true}, + {"/hive decision B", unparkCommandDecision, "", "B", true}, + {"/hive revised", "", "", "", false}, + {"> /hive revise", "", "", "", false}, + {"```\n/hive revise\n```", "", "", "", false}, + {"/hive", "", "", "", false}, + {"please /hive revise", "", "", "", false}, + } + for _, c := range cases { + cmd, ok := parseUnparkCommandFor(c.body, verbs) + if ok != c.ok || cmd.Kind != c.kind || cmd.Verb != c.verb || cmd.DecisionText() != c.text { + t.Errorf("parseUnparkCommandFor(%q) = %+v %v, want kind=%q verb=%q text=%q ok=%v", c.body, cmd, ok, c.kind, c.verb, c.text, c.ok) + } + } + // No verbs: a model verb is the unknown command it always was. + if cmd, ok := parseUnparkCommandFor("/hive revise", nil); ok || cmd.Kind != unparkCommandNone { + t.Fatalf("unbound: %+v %v", cmd, ok) + } + if !isUnparkWatermarkCommandFor("/hive revise", verbs) || isUnparkWatermarkCommand("/hive revise") { + t.Fatal("an answered model reply is a watermark only on a bound repository") + } +} + +func TestModelReplyVerbsFollowStateAndSkipHiveDefault(t *testing.T) { + p := techdocsReplyProfile(t) + if got := modelReplyVerbs(p, []string{stagelabels.IssueNeedsDecision.Label(), "needs-human"}); strings.Join(got, ",") != "approve analysis,revise" { + t.Fatalf("045 verbs = %v", got) + } + if got := modelReplyVerbs(p, []string{"needs-human"}); got != nil { + t.Fatalf("no stage label: %v", got) + } + if got := modelReplyVerbs(hivedefault.Profile(), []string{stagelabels.IssueNeedsDecision.Label()}); got != nil { + t.Fatalf("hive-default must offer no comment verbs, got %v", got) + } + if got := modelReplyVerbs(nil, []string{stagelabels.IssueNeedsDecision.Label()}); got != nil { + t.Fatalf("nil profile: %v", got) + } +} + +func TestSweepIssueUnparkCommandsModelReplyAppliesMappedLabel(t *testing.T) { + issues := []unparkWireIssue{modelParkedIssue(7, humanComment(11, "maintainer", "/hive Approve analysis — go with the shorter outline"))} + server, rec := newUnparkServer(t, "org", "repo", issues, map[string]string{"maintainer": "write"}) + c := newTestClient(t, server, "org", []string{"repo"}) + p := techdocsReplyProfile(t) + var audited []IssueUnparkEvent + + result, err := c.SweepIssueUnparkCommands(context.Background(), IssueUnparkSweepOptions{ + WorkflowFor: func(owner, repo string) *workflowmodel.Profile { + if owner != "org" || repo != "repo" { + t.Fatalf("WorkflowFor(%q,%q)", owner, repo) + } + return p + }, + Audit: func(e IssueUnparkEvent) { audited = append(audited, e) }, + }) + if err != nil { + t.Fatalf("sweep: %v", err) + } + if len(result.Unparked) != 1 || result.Unparked[0].Number != 7 { + t.Fatalf("expected issue 7 un-parked, got %+v", result.Unparked) + } + if got := result.Unparked[0].Decision; got != "approve analysis: — go with the shorter outline" { + t.Fatalf("decision = %q", got) + } + if len(audited) != 1 || audited[0].CommentURL == "" { + t.Fatalf("audit = %+v", audited) + } + added := strings.Join(rec.added[7], ",") + if !strings.Contains(added, HumanAckLabel) || !strings.Contains(added, "docs/040-draft-under-way") { + t.Fatalf("expected %s and the mapped model label added, got %v", HumanAckLabel, rec.added[7]) + } + if !strings.Contains(strings.Join(rec.removed[7], ","), "needs-human") { + t.Fatalf("needs-human is answered by the reply, got %v", rec.removed[7]) + } + joined := strings.Join(rec.posted[7], "\n") + if !strings.Contains(joined, "Un-parked by @maintainer. Decision: approve analysis") || !strings.Contains(joined, "Workflow reply `approve analysis` moves the item from `analysis-review` to `draft-under-way`; `docs/040-draft-under-way` applied.") { + t.Fatalf("reply = %v", rec.posted[7]) + } + if !strings.Contains(joined, unparkReplyMarkerPrefix+"11 -->") { + t.Fatalf("reply must answer comment 11, got %v", rec.posted[7]) + } +} + +func TestSweepIssueUnparkCommandsModelVerbUnknownWhenUnbound(t *testing.T) { + issues := []unparkWireIssue{modelParkedIssue(7, humanComment(11, "maintainer", "/hive revise"))} + server, rec := newUnparkServer(t, "org", "repo", issues, map[string]string{"maintainer": "write"}) + c := newTestClient(t, server, "org", []string{"repo"}) + + for name, opts := range map[string]IssueUnparkSweepOptions{ + "no lookup": {}, + "nil profile": {WorkflowFor: func(string, string) *workflowmodel.Profile { return nil }}, + "hive-default": {WorkflowFor: func(string, string) *workflowmodel.Profile { return hivedefault.Profile() }}, + } { + result, err := c.SweepIssueUnparkCommands(context.Background(), opts) + if err != nil { + t.Fatalf("%s: sweep: %v", name, err) + } + if len(result.Unparked) != 0 || len(rec.added[7]) != 0 || len(rec.removed[7]) != 0 { + t.Fatalf("%s: a model verb on an unbound repo must not act: %+v added=%v removed=%v", name, result.Unparked, rec.added[7], rec.removed[7]) + } + for _, body := range rec.posted[7] { + if strings.Contains(body, "Un-parked") || strings.Contains(body, "Workflow reply") { + t.Fatalf("%s: unexpected reply %q", name, body) + } + } + } +} + +func TestRecordOperatorIssueModelReply(t *testing.T) { + server, rec := newUnparkServer(t, "org", "repo", []unparkWireIssue{modelParkedIssue(7), modelParkedIssue(8)}, nil) + c := newTestClient(t, server, "org", []string{"repo"}) + p := techdocsReplyProfile(t) + + event, err := c.RecordOperatorIssueModelReply(context.Background(), "org/repo", 7, "maintainer", "Revise", " section 2 is thin ", p) + if err != nil { + t.Fatalf("reply: %v", err) + } + if event.Decision != "revise: section 2 is thin" || event.Actor != "maintainer" { + t.Fatalf("event = %+v", event) + } + added := strings.Join(rec.added[7], ",") + if !strings.Contains(added, HumanAckLabel) || !strings.Contains(added, "techdocs/analysis") { + t.Fatalf("expected %s and the event label added, got %v", HumanAckLabel, rec.added[7]) + } + joined := strings.Join(rec.posted[7], "\n") + if !strings.Contains(joined, "Workflow reply `revise` moves the item from `analysis-review` to `analysing`; `techdocs/analysis` applied.") || !strings.Contains(joined, "hive dashboard") { + t.Fatalf("reply = %v", rec.posted[7]) + } + + for name, c2 := range map[string]struct { + verb string + profile *workflowmodel.Profile + }{"unknown verb": {"ship it", p}, "wrong state verb": {"approve", p}, "nil profile": {"revise", nil}, "hive-default": {"revise", hivedefault.Profile()}} { + if _, err := c.RecordOperatorIssueModelReply(context.Background(), "org/repo", 8, "maintainer", c2.verb, "", c2.profile); !errors.Is(err, ErrUnknownModelReply) { + t.Errorf("%s: err = %v, want ErrUnknownModelReply", name, err) + } + } + if _, err := c.RecordOperatorIssueModelReply(context.Background(), "org/repo", 8, "", "revise", "", p); err == nil { + t.Error("blank actor must be refused") + } + if len(rec.added[8])+len(rec.posted[8]) != 0 { + t.Fatalf("refused replies must write nothing, got added=%v posted=%v", rec.added[8], rec.posted[8]) + } +} + +func TestRecordOperatorIssueModelReplyRefusesUnparkedIssue(t *testing.T) { + // A verb-less state: the issue is at 045 only by label, so the model + // offers verbs, but without a parking label there is nothing to answer. + issue := modelParkedIssue(9) + issue.Labels = []wireLabel{{Name: "bug"}} + server, rec := newUnparkServer(t, "org", "repo", []unparkWireIssue{issue}, nil) + c := newTestClient(t, server, "org", []string{"repo"}) + if _, err := c.RecordOperatorIssueModelReply(context.Background(), "org/repo", 9, "maintainer", "revise", "", techdocsReplyProfile(t)); !errors.Is(err, ErrUnknownModelReply) { + t.Fatalf("err = %v", err) + } + if len(rec.added[9])+len(rec.posted[9]) != 0 { + t.Fatal("must write nothing") + } +} + +func TestRecordOperatorIssueModelReplyArgumentErrors(t *testing.T) { + server, _ := newUnparkServer(t, "org", "repo", []unparkWireIssue{modelParkedIssue(7)}, nil) + c := newTestClient(t, server, "org", []string{"repo"}) + p := techdocsReplyProfile(t) + var nilClient *Client + if _, err := nilClient.RecordOperatorIssueModelReply(context.Background(), "org/repo", 7, "m", "revise", "", p); !errors.Is(err, ErrNoGitHubClient) { + t.Errorf("nil client: %v", err) + } + if _, err := c.RecordOperatorIssueModelReply(context.Background(), "org/repo", 0, "m", "revise", "", p); err == nil { + t.Error("issue 0 must be refused") + } + if _, err := c.RecordOperatorIssueModelReply(context.Background(), "org/../x", 7, "m", "revise", "", p); err == nil { + t.Error("invalid repo must be refused") + } + if _, err := c.RecordOperatorIssueModelReply(context.Background(), "org/repo", 404, "m", "revise", "", p); err == nil { + t.Error("missing issue must surface the read error") + } +} + +func TestRenderModelReplyAcceptedBranches(t *testing.T) { + outcome := unparkNeedsHumanOutcome{} + got := renderModelReplyAccepted("m", "revise", workflowmodel.ReplyEffect{Verb: "revise", From: "a", To: "b"}, "", false, outcome) + if !strings.Contains(got, "moves the item from `a` to `b`; the model maps no label to that state, so the reply is recorded here only.") { + t.Fatalf("no-label branch: %s", got) + } + got = renderModelReplyAccepted("m", "hold", workflowmodel.ReplyEffect{Verb: "hold"}, "", false, outcome) + if !strings.Contains(got, "Workflow reply `hold` is recorded; the model declares no transition for it.") { + t.Fatalf("no-transition branch: %s", got) + } +} diff --git a/src/pkg/github/issue_unpark_command.go b/src/pkg/github/issue_unpark_command.go index 65b94b17fe..cbb5603440 100644 --- a/src/pkg/github/issue_unpark_command.go +++ b/src/pkg/github/issue_unpark_command.go @@ -13,6 +13,7 @@ import ( "github.com/hivecommons/hive/pkg/review" "github.com/hivecommons/hive/pkg/stageengine" "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" ) // issueParkingLabels are the labels that park an issue on a person and so @@ -92,6 +93,9 @@ var fixedCommandTokens = []string{"/fixed", "/close"} type unparkCommand struct { Kind unparkCommandKind Decision string + // Verb is the model reply as the model declares it, for + // unparkCommandModelReply only (hivecommons/hive#17620). + Verb string // Text is the whole decision as the person wrote it: the rest of the // command line plus every line after it, trimmed. Decision stays the // first line so the reply's `Decision:` round-trip is unchanged; the PR @@ -178,6 +182,12 @@ type IssueUnparkSweepOptions struct { // ClosedAudit, when set, is called once per parked issue a maintainer's // `/fixed` closed (hivecommons/dibs#459). ClosedAudit func(IssueUnparkEvent) + // WorkflowFor resolves the workflow model bound to a repository + // (hivecommons/hive#17620, RFC phase 4). On a bound repository a parked + // issue also answers `/hive ` for each reply the model declares + // for the issue's current state. nil, or nil for a repository, keeps + // the built-in commands only. + WorkflowFor func(owner, repo string) *workflowmodel.Profile } // PullRequestDecisionEvent records one `/hive decision` on a hive-authored @@ -292,6 +302,10 @@ func (c *Client) SweepIssueUnparkCommands(ctx context.Context, opts IssueUnparkS continue } labelDriven := opts.LabelDriven != nil && opts.LabelDriven(repo) + var profile *workflowmodel.Profile + if opts.WorkflowFor != nil { + profile = opts.WorkflowFor(owner, repoName) + } var policy LabelApprovalPolicy labelApproval := false if labelDriven { @@ -364,7 +378,7 @@ func (c *Client) SweepIssueUnparkCommands(ctx context.Context, opts IssueUnparkS continue } result.Seen++ - acted, err := c.tryUnparkIssue(ctx, repo, owner, repoName, issue, cutoff, labelDriven, unparkLabelApproval{policy: policy, enabled: labelApproval, audit: opts.LabelApprovalAudit}, result, opts.Audit, opts.ClosedAudit) + acted, err := c.tryUnparkIssue(ctx, repo, owner, repoName, issue, cutoff, labelDriven, unparkLabelApproval{policy: policy, enabled: labelApproval, audit: opts.LabelApprovalAudit}, profile, result, opts.Audit, opts.ClosedAudit) if err != nil { if c.noteArchivedWrite(strings.ToLower(owner+"/"+repoName), err) { if c.logger != nil { @@ -439,7 +453,7 @@ type unparkLabelApproval struct { // gets no hint. With label approval (hivecommons/hive#11313) a trusted // acceptance label is acted on first, and `/hive approve` / `/hive decision` // remove only the park labels the hive added itself. -func (c *Client) tryUnparkIssue(ctx context.Context, displayRepo, owner, repo string, issue *gh.Issue, cutoff time.Time, labelDriven bool, la unparkLabelApproval, result *IssueUnparkSweepResult, audit, closedAudit func(IssueUnparkEvent)) (bool, error) { +func (c *Client) tryUnparkIssue(ctx context.Context, displayRepo, owner, repo string, issue *gh.Issue, cutoff time.Time, labelDriven bool, la unparkLabelApproval, profile *workflowmodel.Profile, result *IssueUnparkSweepResult, audit, closedAudit func(IssueUnparkEvent)) (bool, error) { number := issue.GetNumber() comments, err := c.listIssueComments(ctx, owner, repo, number) if err != nil { @@ -466,7 +480,8 @@ func (c *Client) tryUnparkIssue(ctx context.Context, displayRepo, owner, repo st } answered := c.answeredUnparkCommentIDs(comments) - candidate, command, err := c.eligibleUnparkCommand(ctx, owner, repo, comments, answered, cutoff, labelDriven && la.enabled) + verbs := issueModelReplyVerbs(profile, issue) + candidate, command, err := c.eligibleUnparkCommand(ctx, owner, repo, comments, answered, cutoff, labelDriven && la.enabled, verbs) if err != nil { return false, err } @@ -518,6 +533,22 @@ func (c *Client) tryUnparkIssue(ctx context.Context, displayRepo, owner, repo st } labels := issueLabelNames(issue.Labels) + if command.Kind == unparkCommandModelReply { + eff, ok := profile.ReplyForNumber(stagelabels.Current(labels).Number(), command.Verb) + if !ok { + return false, nil + } + event, err := c.applyIssueModelReply(ctx, owner, repo, number, labels, actor, eff, command.DecisionText(), candidate.GetID(), "") + if err != nil { + return false, err + } + event.Repo, event.CommentURL = displayRepo, candidate.GetHTMLURL() + result.Unparked = append(result.Unparked, event) + if audit != nil { + audit(event) + } + return true, nil + } needsHuman := unparkNeedsHumanOutcome{} if hasIssueNeedsHumanLabel(labels) { needsHuman = c.needsHumanOutcome(ctx, owner, repo, number, nil) @@ -925,7 +956,10 @@ const unparkCandidateLimit = 5 // every command posted before it is superseded and never replayed, even // after the issue is parked again (hivecommons/hive#14344). Otherwise a // retracted older decision would be acted on once the newer one is answered. -func (c *Client) eligibleUnparkCommand(ctx context.Context, owner, repo string, comments []*gh.IssueComment, answered map[int64]bool, cutoff time.Time, allowTriage bool) (*gh.IssueComment, unparkCommand, error) { +// +// verbs are the bound workflow model's replies for the item's current state +// (hivecommons/hive#17620); nil admits the built-in commands only. +func (c *Client) eligibleUnparkCommand(ctx context.Context, owner, repo string, comments []*gh.IssueComment, answered map[int64]bool, cutoff time.Time, allowTriage bool, verbs []string) (*gh.IssueComment, unparkCommand, error) { checked := 0 for i := len(comments) - 1; i >= 0 && checked < unparkCandidateLimit; i-- { cm := comments[i] @@ -933,7 +967,7 @@ func (c *Client) eligibleUnparkCommand(ctx context.Context, owner, repo string, continue } if answered[cm.GetID()] { - if isUnparkWatermarkCommand(cm.GetBody()) { + if isUnparkWatermarkCommandFor(cm.GetBody(), verbs) { break } continue @@ -946,7 +980,7 @@ func (c *Client) eligibleUnparkCommand(ctx context.Context, owner, repo string, if updated := cm.GetUpdatedAt().Time; updated.After(created) { continue } - cmd, isCommand := parseUnparkCommand(cm.GetBody()) + cmd, isCommand := parseUnparkCommandFor(cm.GetBody(), verbs) if !isCommand && !isUnparkProseAssent(cm.GetBody()) { continue } @@ -969,12 +1003,18 @@ func (c *Client) eligibleUnparkCommand(ctx context.Context, owner, repo string, // isUnparkWatermarkCommand reports whether an answered comment carried a // command that acted on the park state, so nothing older may be replayed. func isUnparkWatermarkCommand(body string) bool { - cmd, ok := parseUnparkCommand(body) + return isUnparkWatermarkCommandFor(body, nil) +} + +// isUnparkWatermarkCommandFor is isUnparkWatermarkCommand with a bound +// model's reply verbs: an answered model reply is a watermark too. +func isUnparkWatermarkCommandFor(body string, verbs []string) bool { + cmd, ok := parseUnparkCommandFor(body, verbs) if !ok { return false } switch cmd.Kind { - case unparkCommandApprove, unparkCommandDecision, unparkCommandFixed: + case unparkCommandApprove, unparkCommandDecision, unparkCommandFixed, unparkCommandModelReply: return true } return false diff --git a/src/pkg/github/pr_unpark_decision.go b/src/pkg/github/pr_unpark_decision.go index 3ee06ed152..547f168aeb 100644 --- a/src/pkg/github/pr_unpark_decision.go +++ b/src/pkg/github/pr_unpark_decision.go @@ -40,7 +40,7 @@ func (c *Client) tryUnparkPullRequest(ctx context.Context, displayRepo, owner, r return false, err } answered := c.answeredUnparkCommentIDs(comments) - candidate, command, err := c.eligibleUnparkCommand(ctx, owner, repo, comments, answered, cutoff, false) + candidate, command, err := c.eligibleUnparkCommand(ctx, owner, repo, comments, answered, cutoff, false, nil) if err != nil { return false, err } diff --git a/src/pkg/workflowmodel/compile.go b/src/pkg/workflowmodel/compile.go index ce30c1ac6f..bf21250f42 100644 --- a/src/pkg/workflowmodel/compile.go +++ b/src/pkg/workflowmodel/compile.go @@ -75,6 +75,9 @@ type Profile struct { Labels LabelSet `json:"labels,omitzero"` // Diagnostics are the warnings left after a successful compile. Diagnostics []Diagnostic `json:"diagnostics,omitempty"` + // replyEffects maps state id → NormalizeReply(verb) → the transition + // the verb releases (replies.go). Derived; never serialised. + replyEffects map[string]map[string]ReplyEffect } // Compile validates m, then checks the lifecycle half and builds the @@ -149,6 +152,7 @@ func (c *compiler) run() { c.columns() c.numbers() + c.replies() c.exits() c.roles() c.events() diff --git a/src/pkg/workflowmodel/replies.go b/src/pkg/workflowmodel/replies.go new file mode 100644 index 0000000000..cdab0fc97c --- /dev/null +++ b/src/pkg/workflowmodel/replies.go @@ -0,0 +1,179 @@ +package workflowmodel + +import ( + "sort" + "strings" +) + +// ReplyEffect is what one human-gate verb does when a person posts it on +// an item in state From (hivecommons/hive#17620, RFC phase 4 follow-up: +// "the change regenerates labels and commands"). The compiler derives it +// from the model: the transition out of From whose gate is released by the +// verb (Gate.Reply), whose Note names it, or whose event is labelled with +// it. A verb with no such transition is still a recognised reply — the +// decision is recorded — but moves nothing. +type ReplyEffect struct { + // Verb is the reply as the model declares it ("approve analysis"). + Verb string `json:"verb"` + From string `json:"from"` + // To is the target state, "" when the model declares no transition + // for the verb. + To string `json:"to,omitempty"` + // Event is the transition's `on` event id. + Event string `json:"event,omitempty"` + // Label is the label a command handler applies to fire the move: the + // event's `labels has X` value when the event observes a label, else + // the model's label entry for To, else "" (record only). + Label string `json:"label,omitempty"` +} + +// NormalizeReply is the comparison form of a verb: lower-cased, with runs +// of whitespace, underscores and hyphens collapsed to one hyphen, so +// `approve analysis`, `approve-analysis` and `Approve_Analysis` are one +// verb on the command line. +func NormalizeReply(verb string) string { + f := strings.FieldsFunc(strings.ToLower(strings.TrimSpace(verb)), func(r rune) bool { + return r == ' ' || r == '\t' || r == '_' || r == '-' + }) + return strings.Join(f, "-") +} + +// RepliesForNumber returns the verbs the state carrying stage number n +// offers, in declaration order; nil when no state carries n or it offers +// none. +func (p *Profile) RepliesForNumber(n int) []string { + if p == nil { + return nil + } + sid, ok := p.StateOfNumber[n] + if !ok { + return nil + } + return append([]string(nil), p.Replies[sid]...) +} + +// Reply resolves verb for an item in state (by id) to its effect; ok is +// false when the state offers no such verb. Matching uses NormalizeReply. +func (p *Profile) Reply(state, verb string) (ReplyEffect, bool) { + if p == nil { + return ReplyEffect{}, false + } + key := NormalizeReply(verb) + if key == "" { + return ReplyEffect{}, false + } + if e, ok := p.replyEffects[state][key]; ok { + return e, true + } + // A declared reply the compiler could not pin to a transition is still + // a recognised verb: record only. + for _, v := range p.Replies[state] { + if NormalizeReply(v) == key { + return ReplyEffect{Verb: v, From: state}, true + } + } + return ReplyEffect{}, false +} + +// ReplyForNumber is Reply for the state carrying stage number n. +func (p *Profile) ReplyForNumber(n int, verb string) (ReplyEffect, bool) { + if p == nil { + return ReplyEffect{}, false + } + sid, ok := p.StateOfNumber[n] + if !ok { + return ReplyEffect{}, false + } + return p.Reply(sid, verb) +} + +// ReplyVerbs is every distinct verb the profile declares, sorted, for +// command-line parsers that must recognise a verb before they know the +// item's state. +func (p *Profile) ReplyVerbs() []string { + if p == nil { + return nil + } + seen := map[string]bool{} + var out []string + for _, verbs := range p.Replies { + for _, v := range verbs { + k := NormalizeReply(v) + if k == "" || seen[k] { + continue + } + seen[k] = true + out = append(out, v) + } + } + sort.Strings(out) + return out +} + +// replies pins each declared verb to the transition it releases. +func (c *compiler) replies() { + m := c.m + gates := map[string]Gate{} + for _, g := range m.Spec.Gates { + gates[g.ID] = g + } + events := map[string]Event{} + for _, e := range m.Spec.Events { + events[e.ID] = e + } + labelOf := map[string]string{} + for _, e := range m.Spec.Labels.Entries { + if e.State != "" && e.Name != "" { + if _, dup := labelOf[e.State]; !dup { + labelOf[e.State] = e.Name + } + } + } + // match reports how well t answers key: 3 gate reply, 2 note, 1 event + // label/id, 0 no match. + match := func(t Transition, key string) int { + if g, ok := gates[t.GateRef]; ok && t.GateRef != "" && NormalizeReply(g.Reply) == key { + return 3 + } + if NormalizeReply(t.Note) == key { + return 2 + } + if ev, ok := events[t.On]; ok && (NormalizeReply(ev.Label) == key || NormalizeReply(ev.ID) == key) { + return 1 + } + return 0 + } + for sid, verbs := range c.p.Replies { + for _, v := range verbs { + key := NormalizeReply(v) + if key == "" { + continue + } + best, bestScore := Transition{}, 0 + for _, t := range m.Spec.Transitions { + if t.From != sid { + continue + } + if s := match(t, key); s > bestScore { + best, bestScore = t, s + } + } + if bestScore == 0 { + continue + } + eff := ReplyEffect{Verb: v, From: sid, To: best.To, Event: best.On} + if ev, ok := events[best.On]; ok && ev.Fact.Fact == "labels" && ev.Fact.Op == OpHas && ev.Fact.Value != "" { + eff.Label = ev.Fact.Value + } else if l, ok := labelOf[best.To]; ok { + eff.Label = l + } + if c.p.replyEffects == nil { + c.p.replyEffects = map[string]map[string]ReplyEffect{} + } + if c.p.replyEffects[sid] == nil { + c.p.replyEffects[sid] = map[string]ReplyEffect{} + } + c.p.replyEffects[sid][key] = eff + } + } +} diff --git a/src/pkg/workflowmodel/replies_test.go b/src/pkg/workflowmodel/replies_test.go new file mode 100644 index 0000000000..7090e92982 --- /dev/null +++ b/src/pkg/workflowmodel/replies_test.go @@ -0,0 +1,99 @@ +package workflowmodel + +import ( + "slices" + "testing" +) + +func TestNormalizeReply(t *testing.T) { + for in, want := range map[string]string{ + "approve analysis": "approve-analysis", " Approve_Analysis ": "approve-analysis", "approve--analysis": "approve-analysis", + "decide:approve": "decide:approve", "": "", " ": "", + } { + if got := NormalizeReply(in); got != want { + t.Errorf("NormalizeReply(%q)=%q want %q", in, got, want) + } + } +} + +func TestProfileRepliesResolveToTransitions(t *testing.T) { + m := techdocs(t) + m.Spec.Labels = LabelSet{Prefix: "docs", Entries: []LabelEntry{{Name: "docs/040-draft-under-way", State: "draft-under-way"}, {Name: "docs/090-approved", State: "approved"}}} + p, _, err := Compile(m) + if err != nil { + t.Fatal(err) + } + if got := p.RepliesForNumber(45); !slices.Equal(got, []string{"approve analysis", "revise"}) { + t.Fatalf("RepliesForNumber(45)=%v", got) + } + if got := p.RepliesForNumber(10); got != nil { + t.Fatalf("RepliesForNumber(10)=%v", got) + } + if got := p.RepliesForNumber(999); got != nil { + t.Fatalf("RepliesForNumber(999)=%v", got) + } + if got := p.ReplyVerbs(); !slices.Equal(got, []string{"approve", "approve analysis", "hand back", "request changes", "revise"}) { + t.Fatalf("ReplyVerbs=%v", got) + } + + // Gate reply wins: the gate analysis-approved releases the move to + // draft-under-way, whose label entry becomes the label to apply. + eff, ok := p.ReplyForNumber(45, "Approve Analysis") + if !ok || eff.Verb != "approve analysis" || eff.From != "analysis-review" || eff.To != "draft-under-way" || eff.Event != "draft-opened" || eff.Label != "docs/040-draft-under-way" { + t.Fatalf("approve analysis: %+v %v", eff, ok) + } + // Transition note: `revise` fires analysis-posted, whose fact observes + // the techdocs/analysis label, so that label is applied. + eff, ok = p.Reply("analysis-review", "revise") + if !ok || eff.To != "analysing" || eff.Event != "analysis-posted" || eff.Label != "techdocs/analysis" { + t.Fatalf("revise: %+v %v", eff, ok) + } + // A declared verb with no transition is recognised but moves nothing. + eff, ok = p.Reply("analysing", "hand-back") + if !ok || eff.Verb != "hand back" || eff.To != "" || eff.Label != "" { + t.Fatalf("hand back: %+v %v", eff, ok) + } + eff, ok = p.ReplyForNumber(50, "approve") + if !ok || eff.To != "approved" || eff.Label != "docs/090-approved" { + t.Fatalf("approve: %+v %v", eff, ok) + } + // Not offered in this state, unknown state, unknown number, blank verb. + for _, c := range []struct { + state, verb string + }{{"analysis-review", "approve"}, {"requested", "approve analysis"}, {"nope", "revise"}, {"analysis-review", " "}} { + if _, ok := p.Reply(c.state, c.verb); ok { + t.Errorf("Reply(%q,%q) accepted", c.state, c.verb) + } + } + if _, ok := p.ReplyForNumber(999, "approve"); ok { + t.Error("ReplyForNumber(999) accepted") + } + var nilP *Profile + if nilP.RepliesForNumber(45) != nil || nilP.ReplyVerbs() != nil { + t.Error("nil profile must answer nil") + } + if _, ok := nilP.Reply("x", "y"); ok { + t.Error("nil profile Reply accepted") + } + if _, ok := nilP.ReplyForNumber(45, "y"); ok { + t.Error("nil profile ReplyForNumber accepted") + } +} + +// A verb matched only by its event's label or id still resolves. +func TestProfileReplyMatchesEventLabel(t *testing.T) { + m := techdocs(t) + for i := range m.Spec.States { + if m.Spec.States[i].ID == "requested" { + m.Spec.States[i].Lifecycle.Replies = []string{"Accepted"} + } + } + p, _, err := Compile(m) + if err != nil { + t.Fatal(err) + } + eff, ok := p.ReplyForNumber(10, "accepted") + if !ok || eff.To != "analysing" || eff.Event != "accepted" || eff.Label != "techdocs/accepted" { + t.Fatalf("accepted: %+v %v", eff, ok) + } +} From 1fbd09200b9c0f18db9c6bc494d5e143baffcaaa Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 11 Nov 2026 10:00:31 -0700 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=96=20workflow=20models:=20documen?= =?UTF-8?q?t=20label=20GC=20and=20model-defined=20replies?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Append "Label GC and model commands (RFC phase 4, follow-up)" to the design doc — the provisioned record, the safety checks a deletion must pass, the workflow.label_gc knob, how a model's replies flow through the comment parser, the un-park sweep and the dashboard pill, and the gaps left (PR-state replies, un-parked states) — add a "Model-defined replies" section to maintainer-commands.md, and the changelog fragment. Refs hivecommons/hive#17620 Signed-off-by: Andrew Anderson --- .../added-workflowmodel-label-gc-commands.md | 1 + src/docs/design/workflow-models.md | 79 +++++++++++++++++++ src/docs/maintainer-commands.md | 13 +++ 3 files changed, 93 insertions(+) create mode 100644 changelog.d/added-workflowmodel-label-gc-commands.md diff --git a/changelog.d/added-workflowmodel-label-gc-commands.md b/changelog.d/added-workflowmodel-label-gc-commands.md new file mode 100644 index 0000000000..70c3ff85f7 --- /dev/null +++ b/changelog.d/added-workflowmodel-label-gc-commands.md @@ -0,0 +1 @@ +- **workflow models:** the stage engine now remembers which model labels it provisioned per repository and, on unbind or rebind to a model with a different label set, deletes the stale ones — only labels it created, outside the built-in stage family and worn by no open issue or PR; each deletion is audited `workflow_label_removed` and `workflow.label_gc: false` keeps everything. A bound model's `replies` are now offered by the Activity Monitor's human-gate pill and accepted as `/hive ` on parked issues, applying the label the model maps to the reply's target state ([#17620](https://github.com/hivecommons/hive/issues/17620)) diff --git a/src/docs/design/workflow-models.md b/src/docs/design/workflow-models.md index 9a08e4a526..d0ba75bc70 100644 --- a/src/docs/design/workflow-models.md +++ b/src/docs/design/workflow-models.md @@ -394,3 +394,82 @@ fixture under `pkg/workflowmodel/ingest/testdata/techdocs` carries both. until the label-driven engine half of phase 4 writes model labels onto items. - Branch protection needs `administration:read`; without it the rulesets endpoint is used, which omits legacy protection settings such as `enforce_admins`. + +## Label GC and model commands (RFC phase 4, follow-up) + +Two of the phase-4 backend gaps close here: stale model labels are now reclaimed, and a bound +model's `replies` reach the human gate as commands. + +### Label garbage collection on unbind / rebind + +`ensureStageLabels` already provisions a bound model's `LabelDefs` after the built-in family. It +now also remembers what it provisioned and reconciles on change +(`automerge_stage_labels_gc.go`): + +- **Record.** After each provisioning pass the engine writes one JSON record per repository, + `workflows/provisioned/__.json` under `data.workflows_dir` + (`workflowmodel.ProvisionedLabels{repo, model name@version, hash, labels[]}`, through the + `workflowmodel.ProvisionedStore` interface the workflow store implements). The record is the + hive's memory of which labels *it* created or adopted by recolouring for a model; a label the + repository already had for its own reasons is never in it. +- **Diff.** When the profile hash differs from the record's — a rebind, a new version of the bound + model, or an unbind (lookup returns nil or hive-default) — the engine computes + `previous − current` model labels. +- **Delete, only when safe.** A stale label is deleted only if it is in the record, is not in the + built-in family (`stagelabels.LabelDefsFor` plus the retired spellings in `stagelabels.Renames`), + and no open issue or PR wears it (one `label:"x" is:open` search per label; a failed search keeps + the label and logs it). Anything kept stays in the record so the next pass retries it. Every + deletion is audited as `workflow_label_removed` with the repository, label and the model key it + belonged to. +- **Knob.** `workflow.label_gc` (`WorkflowConfig.LabelGC`, default `true`). `false` keeps every + label and logs what would have gone; the record is still maintained, so turning it back on + reclaims what accumulated. The knob is yaml-only (no Settings control; allowlisted in + `settings_parity_allowlist.txt`). +- **Zero change for unbound repositories.** With no `ProvisionedStore` wired, or for a repository + that was never bound, nothing is remembered and nothing is deleted; the pre-P4 path is unchanged + and its tests are byte-identical. + +### Model replies as human-gate commands + +A model's `replies[state]` lists the verbs a human may answer the gate with. They now flow through +three places, all for a repository bound to a non-default model only: + +- **Lookup.** `Profile.RepliesForNumber(stage)` returns the verbs for the state at a stage number; + `Profile.ReplyForNumber(stage, verb)` resolves one to a `ReplyEffect{Verb, From, To, Label}` — + the transition the model declares with that verb as its `on` event (if any), the target state, + and the label `labels.entries` maps to that state (if any). `NormalizeReply` folds case, inner + whitespace and a leading slash so "Approve Analysis", "approve analysis" and "/approve analysis" + are one verb. +- **Comments.** The `/hive` parser (`parseUnparkCommandFor`) tries the model's verbs first — + multi-word, longest match wins, trailing punctuation trimmed, the rest of the line is the + decision text — then the built-ins. With no verbs it *is* the old parser, so `/hive approve` on + an unbound repository is exactly what it was. On a parked issue the sweep answers a model verb + with `applyIssueModelReply`: the parking labels are cleared as for `/hive approve` + (`approved-direction` added, `needs-human` lifted), the mapped label is applied when there is one + (audited `hive_label_applied` with `reply=`), and one reply comment is posted that begins + with the same `Decision:` sentence the decision history reads, then says what the model did + ("moves the item from `a` to `b`; `label` applied" / "…the model maps no label to that state" / + "is recorded; the model declares no transition for it"). Answered replies are idempotency + watermarks like the built-ins. cmd/hive passes the stage engine's `WorkflowFor` to the un-park + sweep so comments see the same binding the labeller does. +- **Dashboard.** The tracker payload's `workflows.repos[].replies` maps stage number → + verbs (hive-default's block carries none). `stageTrackerHumanGateVerbs` appends them after the + built-in verbs, deduped by label, as `wf:` actions; choosing one prompts for an optional + note and POSTs `{"decision":"model-reply","reply":"","comment":…}` to + `/api/repos/{repo}/items/{n}/decision`. The handler resolves the bound profile + (`workflowProfileForRepo`), refuses unbound repositories and verbs the model does not offer at + the item's state with 409, PRs with 400, and otherwise runs the same `applyIssueModelReply` + path, audited `repo_item_decision_model_reply`. + +### Known gaps (phase 4 follow-up) + +- Model replies act on **parked issues** only. A verb declared for a PR state (TechDocs' + `draft-review: approve / request changes`) is not offered by the pill or honoured in comments; PRs + keep GitHub's native review signal. Un-parked issue states with replies are likewise not + answered — the reply needs a gate to answer. +- The pill offers model verbs only where it already shows a human gate; a model state with replies + but no `needs-human` / needs-decision label on the item shows nothing extra. +- Label GC trusts the provisioned record: labels created by an earlier hive build (before the + record existed) are adopted into the record on the next provisioning pass only while the model + still declares them; labels a model dropped *before* this change shipped are never reclaimed + automatically. diff --git a/src/docs/maintainer-commands.md b/src/docs/maintainer-commands.md index 251108f7a8..24dc873d42 100644 --- a/src/docs/maintainer-commands.md +++ b/src/docs/maintainer-commands.md @@ -164,6 +164,19 @@ assent, Hive posts a hint asking for `/hive approve` or `/hive decision ` and leaves all labels unchanged. This avoids turning casual agreement into a state-changing instruction. +## Model-defined replies + +A repository bound to a [workflow model](design/workflow-models.md) may +declare its own human-gate verbs per state (`replies`). On a parked issue in +such a repository, `/hive ` with one of those verbs — multi-word verbs +are fine, case does not matter — is accepted like `/hive decision`: the +parking labels are cleared, `approved-direction` is added, the label the model +maps to the verb's target state is applied when it declares one, and the reply +comment says what the model did with the verb. Any text after the verb is kept +as the decision. The Activity Monitor's human-gate pill offers the same verbs +after the built-in ones. Repositories without a binding, and pull requests, +behave exactly as described above; the model's verbs are not recognised there. + ## Idempotency markers Hive marks its standing parked-issue notice with From 238d1bb27d4423662f1429b34a34ffc75d33bb2a Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 11 Nov 2026 10:24:21 -0700 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=8C=B1=20workflow=20models:=20mark=20?= =?UTF-8?q?the=20model-reply=20label=20write=20solicited;=20refresh=20a=20?= =?UTF-8?q?client.go=20citation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The label a model reply applies is written because a maintainer answered the gate — `/hive ` in a comment or the pill on the dashboard — so it is a solicited write for the writeback ratchet, like the rest of the un-park path. The RankActionableIssues citation in scale-envelope.md moved with the RecordWorkflowLabelRemoved helper added above it. Refs hivecommons/hive#17620 Signed-off-by: Andrew Anderson --- src/docs/scale-envelope.md | 2 +- src/pkg/github/issue_model_reply.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index 8b3ab3e0b5..ea6cfeadf6 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:5247-5257`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5263-5273`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests). diff --git a/src/pkg/github/issue_model_reply.go b/src/pkg/github/issue_model_reply.go index 1853557a56..20bbba616f 100644 --- a/src/pkg/github/issue_model_reply.go +++ b/src/pkg/github/issue_model_reply.go @@ -97,7 +97,7 @@ func (c *Client) applyIssueModelReply(ctx context.Context, owner, repo string, n } applied := "" if eff.Label != "" && !labelPresent(labels, eff.Label) { - if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{eff.Label}); err != nil { + if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{eff.Label}); err != nil { // writeback:solicited a maintainer answered the gate with this model verb (comment or dashboard) return IssueUnparkEvent{}, fmt.Errorf("adding %s to %s/%s#%d: %w", eff.Label, owner, repo, number, err) } c.recordWriteAudit(AuditActionHiveLabelApplied, hiveWriteMeta(),