Companion to ADR-0025, which is the
authoritative definition of every interface named below. Six PRs, each
≤ ~600 LOC, designed so PR-A, PR-B and (after B) PR-C/PR-D can be worked in
parallel by different agents. Base branch v5.
PR-A goldens + shadow harness ─────────────┐
PR-B pkg skeleton (interfaces, Facts, adapters) ──┬── PR-C single writer + admission test ──┐
└── PR-D relay/claim paths submit facts ──┼── PR-E flag, migration, docs ── PR-F delete legacy
PR-A and PR-B are independent. PR-C and PR-D depend only on PR-B (they can
be developed against PR-B's branch and rebased). PR-E depends on A, B, C.
PR-F is a follow-up after 48 h in enforce.
PR-F's remaining PR-side relocation (#13779) puts the classifier and pass
post-steps in pkg/stageengine/derive_pr*.go. pkg/stageengine/prstage
owns the lane reason vocabulary and shared observation shapes; automerge
only gathers facts and previews through engine helpers. Both derivers are
built in: the temporary SetDerivers registry and PR adapter are removed.
The PR goldens now live in pkg/stageengine/testdata/stage_goldens; a thin
automerge facts-fold parity replay is retained for one release. Review prose
classification lives in the dependency-free pkg/review/reviewtext leaf,
avoiding the review → config → stageengine import cycle.
Scope: freeze today's behaviour. No production code changes.
src/pkg/stageengine/testdata/stage_goldens/*.json: one fixture per lane × reason × verdict × author-kind × adoption combination reachable inClassifyStage/ResolveStage(src/pkg/stageengine/derive_pr_classify.go:261,src/pkg/stageengine/derive_pr_classify.go:454), serialised as[]stageObservation→{stage, rank, reason, role, terminal}. Generated by ago test -run TestStageGoldens -updateflag; checked in.src/pkg/github/testdata/issue_stage_goldens/*.json: one per bucket × claim kind × park label × likely-done × covering-PR stage forIssueStageFor(src/pkg/github/issue_stage_labels.go:205).src/pkg/github/automerge/stage_goldens_test.go,src/pkg/github/issue_stage_goldens_test.go: replay fixtures; fail on any diff.src/pkg/stagelabels/shadowdiff/(tiny):Diff(legacy, engine Decision) []Mismatchand aRecorderthat countsstage_shadow_mismatch_total{kind,legacy,engine}and logs one line per distinct mismatch. Pure; no engine import. (Served the rollout; deleted with the legacy comparator in PR-F.)
Tests: the golden tests themselves; shadowdiff unit test.
Files touched: ~6 new, 0 modified. Depends on: nothing.
Scope: land the ADR's types verbatim and wrap today's derivation behind them without moving its logic.
src/pkg/stageengine/{facts.go,decision.go,deriver.go,writer.go,reconciler.go,transition.go,facts_sink.go,mode.go,metrics.go}: the interfaces and types exactly as in ADR-0025 §Design.New(Options)returns a reconciler whoseReconcilederives, callsExpected, records throughStore.Observe, and inModeEnforcecallsWriter.Apply; inModeShadowit callsOptions.Legacyand the shadow recorder; inModeOffit returns without doing anything.transition_table.go:Expected(kind, from, to)generated from the mermaid diagram (src/docs/labels-and-control-signals/stage-labels.md:120) plusstagelabels.IsRegressionrules;transition_table_test.goasserts the table matches the diagram (parse the fenced block).- Adapters (no logic moved yet):
src/pkg/github/automerge/stage_facts.go:factsFrom([]stageObservation) stageengine.FactsandprDeriverAdapterimplementingstageengine.Deriverby convertingLaneFactback tostageObservationand callingresolveStage, then applying ApplyStageLabels' pure post-steps (07x author-kind split, normalized-fixing guard,RouteHuman, DCO override, 074 yield) fromPRFacts.Pass(stageengine.PRPassFacts), which the pass fills with the forge reads and store state those steps consumed. The shadow comparison is therefore written-vs-derived, andTestStageGoldensEngineParityholds the deriver to every golden'sfinal_stage/final_reason.src/pkg/github/issue_stage_facts.go:factsFrom(IssueStageInput) stageengine.FactsandissueDeriverAdapterwrappingIssueStageFor.- Both adapters originally backed
stageengine.DeriveIssue/DerivePRthroughSetDerivers(issue, pr Deriver). PR-F moved both bodies into the engine and removed that temporary registry (#13778, #13779).
- Property test
TestReconcileIdempotent: for randomFacts,Reconciletwice with a fake writer → second call writes nothing and the item carries exactly onestage/*label.
Tests: adapters round-trip the PR-A goldens unchanged (if PR-A has landed; otherwise a smaller inline set); idempotency property test; transition-table test. Files touched: ~10 new, 2 new adapter files in existing packages. Depends on: nothing (uses PR-A goldens when present).
Scope: one writer, every sweep uses it.
src/pkg/github/stage_writer.go:type stageWriter struct{ c *Client }implementingstageengine.StageWriteroverstagelabels.Enforcewith a per-Refmutex and the existing fresh-read/journal behaviour fromsrc/pkg/github/stage_labeler.go:63. This is the only implementation.src/pkg/github/automerge/automerge_stage_labels.go:ApplyStageLabelsbuildsFactsper PR and callsReconciler.ReconcileBatch; deleteengineStageLabeler(replaced bypkg/github/stage_writer.go). The 072 nudge / 074 adoption hooks read the returnedTransitions instead of the local verdict.src/pkg/github/issue_stage_labels.go:SyncIssueStageLabelsbuildsFactsand callsReconcileBatch; the PR-link safeguard stays, keyed off theTransition.src/pkg/stageengine/admission_test.go: walkssrc/withgo/ast; fails if any file outsidestage_writer.goandpkg/stagelabelscallsAddLabels/RemoveLabel*/EnsureLabel*with an argument that is astage/literal,stagelabels.*.Label(),claims.LabelClaimed,claims.LabelPRInProgressorCoveredByPRLabel, or implementsstageengine.StageWriter. Allow-list is a short slice in the test; PR-D empties it.- Race test
TestRelayVsSweepOneStage(-race): aFactSink.Claimedand aReconcileBatchfor the same ref interleaved N times → exactly one stage label at the end and no anomaly other than the expected 010→020.
Tests: as above plus existing automerge/issue-stage tests passing unchanged
(the writer is the same Enforce). Files touched: ~5 modified, 2 new.
Depends on: PR-B.
Scope: no out-of-cycle code names a stage label.
src/cmd/hive/claimswire.go: ledger hooks callFactSink.Claimed/ClaimReleasedinstead ofclaimStageFor+ label writes (src/cmd/hive/claimswire.go:176-178,src/cmd/hive/claimswire.go:236-238).src/pkg/github/issue_inprogress.go: theclaimrequest submitsInProgress; the sweep's 040 swap becomesCoveredBy(src/pkg/github/issue_inprogress.go:126-141,src/pkg/github/issue_inprogress.go:186).src/pkg/github/prclaims.go: 040 add/remove →CoveredBy/Uncovered(src/pkg/github/prclaims.go:1777,src/pkg/github/prclaims.go:2037).src/pkg/dashboard/contribute_verdict_settle.go:216→CoveredBy.src/pkg/github/issue_request_label.go: an agent request for a parking label becomesParked;agentMayAddLabelkeeps the allow-list for the non-stageneeds-human(src/pkg/github/issue_request_label.go:75).src/pkg/github/legacy_decision_labels.goun-park →Unparked.- Delete
Client.ApplyStageLabeland the stage parameter ofAddLabelsFresh(src/pkg/github/stage_labeler.go:63,src/pkg/github/stage_labeler.go:114). - Vocabulary cleanup (independent of B/C):
claims.LabelClaimedandclaims.LabelPRInProgressrender throughstagelabels(kept as vars for callers); review dispatch usesstagelabels.AdoptedByHive.Label().stagelabelsowns the retired claim spellings, with aliases inclaims. Config registers stage slugs from its own side, removing both the directstagelabels→claimsand indirectstagelabels→config→claimsdependencies so claims can import the vocabulary without a cycle. - Empty the admission-test allow-list.
Tests: existing claimswire/in-progress/prclaims tests rewritten to assert
facts submitted (fake sink) rather than labels written; the fake sink runs a
real reconciler with a fake writer so label expectations still hold.
Files touched: ~8 modified. Depends on: PR-B (the FactSink type); rebases
over PR-C for the allow-list.
Landed as #13009. The
sink hangs off github.Client (StageFacts() / SetStageFactSink); its
default is an enforce-mode reconciler over stagelabels.Shared() whose
Enrich hook re-reads the item (labels, open/closed, issue-vs-PR) before
deriving. Deviation: src/pkg/claims/comments.go keeps its literals —
pkg/config imports pkg/claims and pkg/stagelabels imports pkg/config,
so the import would cycle; TestClaimLabelConstantsMatchStages in
pkg/stagelabels pins the spellings instead. Test doubles live in
src/pkg/stageengine/stageenginetest (Writer, NewSink, Recorder).
Landed (#13010): cmd/hive/stage_engine.go builds the one
stageengine.Options, Client.StageReconciler the one reconciler; the mode
is a runtime switch (stageengine.ModeSwitch) re-read before each sweep,
off was legacy pass-through (retired by PR-F); /api/status.stageEngine and the tracker strip
report mode / anomalies. The original scope follows.
src/pkg/config:governor.labels.stage.engine.mode(off|shadow|enforce, defaultshadowduring the rollout,enforcesince the default flip); Settings → Labels tab exposes it;hivectl configvalidation.cmd/hivewiring: construct onestageengine.New(Options{...})with thestageWriter,stagelabels.Shared(), the adapters and the PR-A shadow recorder; pass it to the automerge engine, issue sweep and relay.- Metrics registered; the activity tracker status strip shows mode, mismatch count (shadow) and anomaly count.
- Docs:
labels-and-control-signals.md(mermaid stays; "How a stage is written" section replaces the direct-write paragraph atsrc/docs/labels-and-control-signals/reference.md:313-316),dashboard-sections.md,config-layering.md, ADR-0025 status → Accepted when enforce is default. - Changelog fragment.
Rollout: ship with shadow on hive's own spoke; after 48 h with
stage_shadow_mismatch_total == 0 and zero duplicate-stage pills (tracker
Healed count 0), flip the spoke to enforce; after a further 48 h flip the
default. Rollback: set mode: off (legacy paths intact until PR-F).
Files touched: ~8. Depends on: PR-A, PR-B, PR-C (PR-D is not required for
shadow but is for the default flip).
Default flip landed (#12999): an unset
governor.labels.stage.engine.mode now yields enforce
(config.DefaultStageEngineMode) after 48 h clean enforce on hive's spoke;
an unparsable value still falls back to shadow, never enforce. A hive
that wants to pause stage writes sets mode: shadow. ADR-0025 is Accepted.
(stageengine.DefaultMode was shadow as the library default until PR-F
retired the legacy comparator; with nothing else able to write it is
enforce too.)
Shipped as three PRs (#13011):
- F1 — retire the legacy comparator (landed):
Options.Legacy,LegacyTable,ModeOff, the shadow-diff recorder (pkg/stagelabels/shadowdiff),stage_shadow_mismatch_totaland the status/strip mismatch fields are gone.shadowis now a pure pause (derive, count, write nothing). The sweeps no longer feed their own derivation to the reconciler; each package registers its deriver at init. Retiring the comparator exposed that the PR adapter's enforce-mode Decision dropped the pass'sStalledand configuredKindLabels(PRPassFactsnow carries both) and kept the role on a terminal PR. - F2 — issue derivation moves in, review-state fold closed (landed):
IssueStageFor's body isstageengine.deriveIssueoverIssueFactsthat now carry the resolved label families (HoldLabel,BlockedReason,UmbrellaLabel,TriageAwaiting,NeedsHumanLabel);Decision.Coveredreplaces the shim's second return.pkg/githubkeeps the one place the hive's configurable label vocabulary meets the engine (resolveIssueLabelFacts, used by the sweep's facts builder, the sink's fresh-read enrichment and thegithub.IssueDeriverwrapper), so the issue goldens stay inpkg/githuband replay through the shim unchanged — the corpus is keyed on labels, and the labels are configuration.cmd/hive/stageengine_wire.gois gone: the issue deriver is built in and automerge registers the PR deriver at init. The ADR's open question is closed:ReviewFacts.Stateis the foldverdictStateFromdefines (Approved →VerdictApproved; unconfigured →VerdictUnavailable;changes_requested/reject/request_changes→VerdictChangesRequested;requires_humanor a decision request →VerdictRequiresHuman; elseVerdictPending), the 050-after-reviews stall was fixed in #13112, and the PR deriver readsStatefor the verdict's routing while the raw verdict string stays for the reason text. - PR derivation body (
classifyStage/resolveStage, ~1,200 lines over the lanes' reason vocabulary) stays inpkg/github/automergebehind thePRDeriveradapter and the PR goldens; moving it is a pure relocation that the goldens pin and is tracked separately (see #13011's close-out comment) rather than held against the epic.
| Gate | Metric | Target |
|---|---|---|
| shadow → enforce (spoke) | stage_shadow_mismatch_total (series retired by PR-F; held at 0) |
0 over 48 h |
| shadow → enforce (spoke) | duplicate-stage pills (Outcome.Healed) |
0 over 48 h |
| enforce → default | stage_transition_anomaly_total |
only pairs explained by a documented event (merge, close, human label edit) |
| any | GitHub REST calls per cycle (hive:issue_stage_labels, stageRESTCaller) |
not above the pre-engine baseline |
-
030 needs PR evidence (#13069):
ClaimFact.PRStarted(ledgerClaim.PRStarted, markerpr_started=true) is set by the start-signal seam only for ahive-open-pr --issuesrequest or a<!-- hive:start branch=… -->/pr=…marker;IssueStageForand the engine adapter derive030-pr-in-progressonly when it is set and020-claimedfor every other live claim or start mark. The diagram andtransition_table.gogained020 → 010,030 → 010(claim released / lapsed with no PR) and020 → 040, so claim expiry is no longer an anomaly. Landed in the same PR for legacy and engine so the shadow mismatch gate stays at 0. -
Covering-PR close and claim reshuffles (#12999): the first
enforcewindow surfaced legitimate undrawn issue edges. The diagram andtransition_table.gogained040 → 010,040 → 030,040 → 020(covering PR closed with nothing / a start marker / the claim still live) and030 → 020(PR evidence lapsed, claim held). -
018 open for discussion (#17150): an open issue labelled
proposal,kind/designorarchitecture discussionwith no live claim derivesstage/018-open-for-discussioninstead of 010 / 015, as does an unlabelled issue whose title opens with[RFC]/RFC:(reasonopen for discussion: rfc title, #18141).pkg/githubresolves the label or title intoIssueFacts.DiscussionLabel; the deriver applies it wherever the issue would otherwise sit unclaimed (the actionable / reporter-triage buckets, and an umbrella whose claim is not staged), and names the label in the reason (open for discussion: proposal). Claims, PR coverage, parks, holds andblockedare unchanged, and the claim gate does not refuse the labels, so a claim still stages 020 / 030.issueProgressbooks040 → 018underhive/partially-addressedas progress (aRefsRFC PR merged, the discussion remains), and leaving 018 is never a regression. The diagram andtransition_table.gogained010 ↔ 018,018 → 020,018 ↔ 045,020 → 018,030 → 018and040 → 018. The stage engine reads labels only, never titles: a 📝 RFC without either label stays 010.
Tracking issue: #12999 Central stage engine (ADR-0025) — one checkbox per PR
above; each PR body carries Refs #<tracking>.