From c75f00f388bfee49bd6e69a0a03ed0630388a693 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 16:34:00 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20Stop=20the=20in-progress=20s?= =?UTF-8?q?weep=20stripping=20workflow-model=20stage=20labels?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A repository bound to a workflow model derives its stage through the model; TechDocs 'Accepted' (number 20) wears stage/020-claimed. The in-progress sweep read that as a claim, found no start mark and removed it; the stage sync re-added it two seconds later, every cycle (cncf/techdocs#395, ~298 flips). The sweep now leaves a trigger label the bound model derives for the issue alone and never withholds the issue for it (a live start mark still withholds). The default FactSink derives through the same per-repository model lookup as the sweeps, installed from the reconciler's options. Fixes #18434 Signed-off-by: Andy Anderson --- .../fixed-18434-model-stage-label-flap.md | 1 + src/pkg/github/client.go | 3 + src/pkg/github/issue_inprogress.go | 32 ++++- src/pkg/github/issue_stage_labels.go | 7 +- src/pkg/github/stage_facts_sink.go | 4 + src/pkg/github/stage_model_owned.go | 82 ++++++++++++ src/pkg/github/stage_model_owned_test.go | 126 ++++++++++++++++++ src/pkg/github/stage_writer.go | 5 + 8 files changed, 258 insertions(+), 2 deletions(-) create mode 100644 changelog.d/fixed-18434-model-stage-label-flap.md create mode 100644 src/pkg/github/stage_model_owned.go create mode 100644 src/pkg/github/stage_model_owned_test.go diff --git a/changelog.d/fixed-18434-model-stage-label-flap.md b/changelog.d/fixed-18434-model-stage-label-flap.md new file mode 100644 index 0000000000..6db3682fe8 --- /dev/null +++ b/changelog.d/fixed-18434-model-stage-label-flap.md @@ -0,0 +1 @@ +- Workflow-model repositories no longer flap `stage/020-claimed` every cycle: the in-progress sweep leaves a stage label the bound model derives for the issue (TechDocs "Accepted") in place and does not treat it as a claim, and out-of-cycle stage facts derive through the same bound model as the sweeps (#18434). diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 519939f971..4c6cb6eb79 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -569,6 +569,9 @@ type Client struct { stageEngineMu sync.Mutex stageWriter *stageWriter stageEngines map[*stagelabels.Store]stageengine.Reconciler + // stageWorkflow is the per-repository workflow model lookup the stage + // engine derives through (stage_model_owned.go, hivecommons/hive#18434). + stageWorkflow atomic.Pointer[stageWorkflowLookup] // baseRefresh is the decision carry's memo (pr_decision_base_refresh.go). baseRefreshOnce sync.Once baseRefresh *BaseRefreshChecker diff --git a/src/pkg/github/issue_inprogress.go b/src/pkg/github/issue_inprogress.go index 97a754af77..1be4942c52 100644 --- a/src/pkg/github/issue_inprogress.go +++ b/src/pkg/github/issue_inprogress.go @@ -311,8 +311,16 @@ func SweepInProgressIssues(ctx context.Context, client *Client, result *Actionab kept = append(kept, issue) continue } + // The bound workflow model may derive this very stage label for the + // issue's state (TechDocs Accepted is number 20): then it is the + // model's, not a claim. Stripping it here only had the stage sync + // put it back two seconds later, every cycle (hivecommons/hive#18434). + // A live start mark still withholds the issue; the label stays. + modelOwned := client.modelOwnsInProgressTrigger(issue) if issueHasPREvidence(issue) { - client.removeInProgressLabel(ctx, &issue, "pr evidence", logger) + if !modelOwned { + client.removeInProgressLabel(ctx, &issue, "pr evidence", logger) + } kept = append(kept, issue) continue } @@ -337,6 +345,10 @@ func SweepInProgressIssues(ctx context.Context, client *Client, result *Actionab "repo", issue.Repo, "issue", issue.Number, "agent", claim.Identity, "started_at", claim.StartedAt, "expires_at", claim.ExpiresAt) } + case modelOwned: + // No live claim and the label is the model's state: the issue + // is not claimed, and the label is not ours to take off. + kept = append(kept, issue) default: client.removeInProgressLabel(ctx, &issue, "start mark lapsed", logger) kept = append(kept, issue) @@ -351,6 +363,24 @@ func SweepInProgressIssues(ctx context.Context, client *Client, result *Actionab return withheld } +// modelOwnsInProgressTrigger reports whether every trigger label the issue +// carries is the stage label its bound workflow model derives (see +// Client.modelOwnsStageLabel). A retired trigger (hive/in-progress) is never +// the model's, so an issue still wearing one is swept as before. +func (c *Client) modelOwnsInProgressTrigger(issue Issue) bool { + owned := false + for _, l := range inProgressTriggerLabels { + if !issueHasLabel(issue.Labels, l) { + continue + } + if !c.modelOwnsStageLabel(issue, l) { + return false + } + owned = true + } + return owned +} + func startedLabel(claim issueclaim.Claim) string { if claim.StartedAt.IsZero() { return "an unrecorded time" diff --git a/src/pkg/github/issue_stage_labels.go b/src/pkg/github/issue_stage_labels.go index 4bf1859d88..f738ea1edd 100644 --- a/src/pkg/github/issue_stage_labels.go +++ b/src/pkg/github/issue_stage_labels.go @@ -392,6 +392,11 @@ func forgeIssueLabels(labels []string, claim *IssueClaimContext) []string { return removeIssueLabel(slices.Clone(labels), CoveredByPRLabel) } +// issueStageInputFrom is the stage input for one actionable issue. +func issueStageInputFrom(issue Issue) IssueStageInput { + return IssueStageInput{Repo: issue.Repo, Number: issue.Number, Labels: forgeIssueLabels(issue.Labels, issue.ClaimContext), Title: issue.Title, ClaimKind: issue.ClaimKind, ClaimedBy: issue.ClaimedBy, PRStarted: issue.ClaimPRStarted, Claim: issue.ClaimContext, Children: issue.Children, AuthorKind: issueAuthorKind(issue), DelegatesWork: hasUnfinishedDelegatedWork(issue.Body), SpekUmbrella: spekmarker.IsUmbrella(issue.Body), UpdatedAt: issue.UpdatedAt, Assignees: issue.Assignees} +} + // IssueStageInputs flattens an enumeration result into one row per open // issue the cycle saw, actionable items first, then every work-detail row. func IssueStageInputs(result *ActionableResult) []IssueStageInput { @@ -400,7 +405,7 @@ func IssueStageInputs(result *ActionableResult) []IssueStageInput { } var out []IssueStageInput for _, issue := range result.Issues.Items { - out = append(out, IssueStageInput{Repo: issue.Repo, Number: issue.Number, Labels: forgeIssueLabels(issue.Labels, issue.ClaimContext), Title: issue.Title, ClaimKind: issue.ClaimKind, ClaimedBy: issue.ClaimedBy, PRStarted: issue.ClaimPRStarted, Claim: issue.ClaimContext, Children: issue.Children, AuthorKind: issueAuthorKind(issue), DelegatesWork: hasUnfinishedDelegatedWork(issue.Body), SpekUmbrella: spekmarker.IsUmbrella(issue.Body), UpdatedAt: issue.UpdatedAt, Assignees: issue.Assignees}) + out = append(out, issueStageInputFrom(issue)) } // Held issues leave the pipeline at enumeration (Hold list, no // work-detail row). They still have to be walked so a stage label diff --git a/src/pkg/github/stage_facts_sink.go b/src/pkg/github/stage_facts_sink.go index 2c0df08b20..481a9db1ed 100644 --- a/src/pkg/github/stage_facts_sink.go +++ b/src/pkg/github/stage_facts_sink.go @@ -78,6 +78,10 @@ func (c *Client) defaultStageFactSink() stageengine.FactSink { Issue: IssueDeriver(), PR: stageengine.PRDeriver(), Logger: c.logger, + // Derive through the repository's bound workflow model, as the + // sweeps do: a fact derived built-in on a model-bound repository + // would write a stage the next sweep reverts (hivecommons/hive#18434). + WorkflowFor: c.stageWorkflowFor, // Shares the process counters with the sweeps' reconciler so // /metrics and /api/status count fact-driven writes too. Metrics: stageengine.DefaultCounters(), diff --git a/src/pkg/github/stage_model_owned.go b/src/pkg/github/stage_model_owned.go new file mode 100644 index 0000000000..1ac946feef --- /dev/null +++ b/src/pkg/github/stage_model_owned.go @@ -0,0 +1,82 @@ +package github + +import ( + "github.com/hivecommons/hive/pkg/stageengine" + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// Workflow-model stage ownership (hivecommons/hive#18434). +// +// A repository bound to a workflow model derives its stage through the +// model (stageengine.DeriveForRepo). A model state reuses the built-in stage +// label for its lifecycle number, so the TechDocs "Accepted" state (number +// 20: waiting on the reviewer to delegate the drafter) wears +// stage/020-claimed although no agent holds a claim. The in-progress sweep +// read that label as a claim, found no hive:claim marker, and stripped it; +// the stage sync two seconds later derived the model state again and put it +// back. cncf/techdocs#395 flapped every enumeration cycle for a day and a +// half. +// +// Two writers now agree: the in-progress sweep leaves a stage label the +// bound model derives for the issue alone (and does not withhold the issue, +// since a model state is not a claim), and the out-of-cycle FactSink derives +// through the same per-repository model lookup as the sweeps. + +// stageWorkflowLookup is the per-repository model lookup, held behind an +// atomic pointer because the sweeps read it while boot installs it. +type stageWorkflowLookup struct { + fn func(owner, repo string) *workflowmodel.Profile +} + +// SetStageWorkflowFor installs the per-repository workflow model lookup the +// stage engine uses (stageengine.Options.WorkflowFor). StageReconciler +// installs it from the options it is first built with, so cmd/hive's boot +// wiring needs nothing extra; tests call it directly. Nil clears it. +func (c *Client) SetStageWorkflowFor(fn func(owner, repo string) *workflowmodel.Profile) { + if c == nil { + return + } + if fn == nil { + c.stageWorkflow.Store(nil) + return + } + c.stageWorkflow.Store(&stageWorkflowLookup{fn: fn}) +} + +// stageWorkflowFor resolves the workflow model bound to owner/repo, or nil +// when none is installed or the repository is unbound. +func (c *Client) stageWorkflowFor(owner, repo string) *workflowmodel.Profile { + if c == nil { + return nil + } + l := c.stageWorkflow.Load() + if l == nil || l.fn == nil { + return nil + } + return l.fn(owner, repo) +} + +// modelOwnsStageLabel reports whether the workflow model bound to the +// issue's repository derives a state for the issue whose stage label is +// label. Such a label is the model's state, not a claim: the in-progress +// sweep must neither strip it nor treat the issue as claimed. The built-in +// hive-default model never owns a label (it is the built-in derivation). +func (c *Client) modelOwnsStageLabel(issue Issue, label string) bool { + owner, name := c.splitRepo(issue.Repo) + p := c.stageWorkflowFor(owner, name) + if p == nil || p.Name == hiveDefaultWorkflowName { + return false + } + f := issueFactsFrom(issueStageInputFrom(issue), func(string, int) stagelabels.Stage { return stagelabels.None }) + f.Ref.Owner, f.Ref.Repo = owner, name + d := stageengine.DeriveFromModel(p, stagelabels.IssueItem).Derive(f) + if d.Abstain || d.ModelState == "" || d.Stage == stagelabels.None { + return false + } + return d.Stage.Label() == label +} + +// hiveDefaultWorkflowName is the built-in model's name +// (workflowmodel.Default); binding it changes nothing about derivation. +const hiveDefaultWorkflowName = "hive-default" diff --git a/src/pkg/github/stage_model_owned_test.go b/src/pkg/github/stage_model_owned_test.go new file mode 100644 index 0000000000..eaec12457e --- /dev/null +++ b/src/pkg/github/stage_model_owned_test.go @@ -0,0 +1,126 @@ +package github + +import ( + "context" + "encoding/json" + "io" + "log/slog" + "os" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/stageengine" + "github.com/hivecommons/hive/pkg/stageengine/stageenginetest" + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// modelOwnedCycles is how many enumeration cycles the flap regression test +// replays: enough for a strip-then-restore loop to show twice. +const modelOwnedCycles = 4 + +func techdocsModelForStage(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) + } + p, diags, err := workflowmodel.Compile(&m) + if err != nil { + t.Fatalf("%v %+v", err, diags) + } + return p +} + +// hivecommons/hive#18434: on a repository bound to a workflow model whose +// state derives stage/020-claimed (TechDocs "accepted"), the in-progress +// sweep stripped the label for want of a start mark and the stage sync put +// it back, every cycle. Replaying sweep + stage reconcile must converge: +// one add on the first cycle, then no add or remove at all, and the issue +// is never withheld as claimed. +func TestModelOwnedStageLabel_ReconcileIsIdempotent(t *testing.T) { + p := techdocsModelForStage(t) + lookup := func(owner, repo string) *workflowmodel.Profile { return p } + + server, removed := sweepServer(t, []string{"a human comment, no claim marker"}) + c := newTestClient(t, server, "acme", []string{"widgets"}) + enableInProgress(c, "hive-a", 2*time.Hour) + c.SetStageWorkflowFor(lookup) + + ref := stageengine.Ref{Owner: "acme", Repo: "widgets", Number: 7, Kind: stagelabels.IssueItem} + w := stageenginetest.NewWriter() + w.Seed(ref, "techdocs/request", "techdocs/accepted") + r := stageengine.New(stageengine.Options{ + Mode: stageengine.ModeEnforce, + Store: stagelabels.NewStore("", nil), + Writer: w, + WorkflowFor: lookup, + Logger: slog.New(slog.NewTextHandler(io.Discard, nil)), + }) + + for cycle := 0; cycle < modelOwnedCycles; cycle++ { + issue := claimIssue() + issue.Labels = w.LabelsOf(ref) + result := &ActionableResult{Issues: IssueResultFromItems([]Issue{issue})} + if withheld := SweepInProgressIssues(context.Background(), c, result, inProgressNow, nil); withheld != 0 { + t.Fatalf("cycle %d: a model state is not a claim, withheld = %d", cycle, withheld) + } + if len(result.Issues.Items) != 1 { + t.Fatalf("cycle %d: issue must stay in the actionable set, got %+v", cycle, result.Issues.Items) + } + if len(*removed) != 0 { + t.Fatalf("cycle %d: in-progress sweep stripped the model's stage label: %v", cycle, *removed) + } + f := issueFactsFrom(issueStageInputFrom(result.Issues.Items[0]), func(string, int) stagelabels.Stage { return stagelabels.None }) + f.Ref = ref + tr, err := r.Reconcile(context.Background(), f) + if err != nil { + t.Fatalf("cycle %d: reconcile: %v", cycle, err) + } + if tr.To != stagelabels.Claimed { + t.Fatalf("cycle %d: model state accepted derives %s, want %s", cycle, tr.To, stagelabels.Claimed) + } + if cycle > 0 && (len(tr.Outcome.Added) > 0 || len(tr.Outcome.Removed) > 0) { + t.Fatalf("cycle %d: label churn: added %v removed %v", cycle, tr.Outcome.Added, tr.Outcome.Removed) + } + } + if !issueHasLabel(w.LabelsOf(ref), stagelabels.Claimed.Label()) { + t.Fatalf("labels = %v, want the model's stage label kept", w.LabelsOf(ref)) + } +} + +// Off the model (no binding, or the issue is in a state whose label is not +// the trigger), the sweep clears a stage/020-claimed with no live mark +// exactly as before. +func TestModelOwnedStageLabel_UnboundOrOtherStateStillClears(t *testing.T) { + p := techdocsModelForStage(t) + cases := []struct { + name string + lookup func(owner, repo string) *workflowmodel.Profile + labels []string + }{ + {"unbound", func(string, string) *workflowmodel.Profile { return nil }, []string{"techdocs/accepted", InProgressLabel}}, + {"model state is not claimed", func(string, string) *workflowmodel.Profile { return p }, []string{"techdocs/request", stagelabels.Claimed.Label()}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + server, removed := sweepServer(t, []string{"just a human comment"}) + c := newTestClient(t, server, "acme", []string{"widgets"}) + enableInProgress(c, "hive-a", 2*time.Hour) + c.SetStageWorkflowFor(tc.lookup) + issue := claimIssue() + issue.Labels = tc.labels + result := &ActionableResult{Issues: IssueResultFromItems([]Issue{issue})} + if withheld := SweepInProgressIssues(context.Background(), c, result, inProgressNow, nil); withheld != 0 { + t.Fatalf("withheld = %d, want 0", withheld) + } + if len(*removed) != 1 { + t.Fatalf("expected the lapsed label removed once, got %v", *removed) + } + }) + } +} diff --git a/src/pkg/github/stage_writer.go b/src/pkg/github/stage_writer.go index c31a90661f..1646a329f8 100644 --- a/src/pkg/github/stage_writer.go +++ b/src/pkg/github/stage_writer.go @@ -94,6 +94,11 @@ func (c *Client) StageReconciler(store *stagelabels.Store, opts *stageengine.Opt if o.Logger == nil && logger != nil { o.Logger = logger } + if o.WorkflowFor != nil { + // The in-progress sweep and the FactSink must derive through the + // same bound model as the sweeps (hivecommons/hive#18434). + c.SetStageWorkflowFor(o.WorkflowFor) + } r := stageengine.New(o) if c.stageEngines == nil { c.stageEngines = map[*stagelabels.Store]stageengine.Reconciler{} From 8d1f29bf7ee36e529e93d1d79b27081e3f6e28e8 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 16:45:01 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Install=20the=20stage=20work?= =?UTF-8?q?flow=20lookup=20in=20configureGitHubClient?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The client-hook guard requires every Set* hook to be applied where the client is (re)built, so a rebuilt client keeps it (#9614). Signed-off-by: Andy Anderson --- src/cmd/hive/github_client_config.go | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/cmd/hive/github_client_config.go b/src/cmd/hive/github_client_config.go index b9908ca338..9db8ab5b1e 100644 --- a/src/cmd/hive/github_client_config.go +++ b/src/cmd/hive/github_client_config.go @@ -170,6 +170,12 @@ func (b *boot) applyGitHubClientConfigHooks(client *github.Client) { // in-progress sweep: a ledger claim whose 🔒 comment was budget-suppressed // must still read as a claim (claimswire.go, ledgerClaimLookup). client.SetIssueClaimLedger(ledgerClaimLookup(func() *claims.Ledger { return b.issueClaims })) + // The bound workflow model lookup the stage engine derives through: the + // in-progress sweep and the out-of-cycle stage facts must agree with the + // sweeps on a model-bound repository (hivecommons/hive#18434, + // stage_model_owned.go). StageReconciler also installs it, but only once + // a sweep builds the reconciler for this client. + client.SetStageWorkflowFor(stageEngineOptions(b.cfg, b.logger).WorkflowFor) // Duplicate-PR claim ledger fallback for the out-of-cycle stage facts: // a claim release on an issue whose covering PR the ledger already holds // re-derives 040, not 010 (stage_facts_sink.go, ledgerCoveringPR).