Repository navigation
Description
Status: Implemented (v5 + v6), follow-ups #18354 #18356 #18357 #18355
Target: v6 (loader, store, viewer behind a flag; built-in workflow untouched), v7 for marketplace publishing
Area: stage engine, dashboard, config, hub
Summary
Hive's lifecycle is built in: the stage engine (ADR-0025, pkg/stageengine) derives stage/* from facts with two hard-coded derivers, DeriveIssue and DerivePR, and the dashboard, commands, gates and lanes all assume that one graph. This RFC adds workflow models: a declared description of a lifecycle (states, events, gates, roles, agent actions, CI checks, bookkeeping) that a repository can be bound to instead of the built-in one. Models are ingested from an existing repository's process (GitHub Actions workflows, Tekton or OpenShift Pipelines, issue templates, labels, branch rules, or a written spec), stored as versioned artifacts, viewed and edited visually, selected or deselected per repository, and later published to a marketplace.
Nothing changes for a hive that does not select a model. The built-in derivers remain the default and are themselves exposed as a read-only model named hive-default so the viewer can show what Hive already does.
Motivation
- The stage graph is the product, and today it is Go code. A project whose lifecycle is not "issue β PR β review β merge" (a docs assessment with three phases and stakeholder confirmation, a release train, a security disclosure process, a CNCF project onboarding checklist) cannot use Hive without Hive learning its process in code.
- Every consumer interprets labels separately: the monitor, the gates, the merge code and the agent prompts each carry their own reading. The October intake design argues for one compiled model that all of them consume; this RFC is its first slice, with inference deferred.
- Operators already store and select other artifacts from the dashboard (knowledge git sources, skills, agent profiles, lanes). Workflows should be the same kind of thing: a saved object with a name, a version, an author and an on/off switch per repository.
- Concrete first customer: the CNCF TechDocs AI-assisted assessment (spec on
nate-double-u/cncf-techdocs, branchai-assisted-assessment-spec). Its lifecycle is already written down in sections 5, 6 and 12 of that spec; it needs an engine, not a redesign.
Guarantees
- No change without selection. A repository with no
workflow:binding derives stages exactly as today. The v5 and v6 goldens (stage_goldens_test.go) are the proof and stay green. - One engine, one writer. Models plug in as a third
Deriverimplementation (DeriveFromModel) behind the existingDeriverinterface (deriver.go:6) and produce the existingDecision(decision.go:10); theReconcilerstays the only label writer. No second state machine. - Deterministic. A model is compiled, not interpreted by an LLM. The compiler refuses ambiguity: a state with no exit, a gate with no owner, an agent action with no human gate after it, two events that fire on the same fact.
- Fail closed. Facts a model does not cover produce "not covered", shown on the monitor as a waiting reason; they never silently fall through to the built-in graph.
- Spoke-owned. Models are selected per repository on the hive that serves it. The hub can list, distribute and later publish; it never binds a model to a spoke's repository.
Design
The model
A versioned document (YAML on disk, JSON over the API) with:
meta: name, version, author, source (ingested-from: github-actions | tekton | issue-templates | spec | hand), description, license.columns: the Activity Monitor columns, ordered, each collecting one or more states (detailed below).states: named, each assigned to a column, a numeric order for thestage/NNN-*label it maps to, the waiting reasons it can show, and whether it is terminal.events: what moves between states β a label applied, a comment command, a PR opened/ready/merged, a check conclusion, a review, a timer β each bound to afactthe engine already has or a new one the ingester adds toFacts.gates: per transition, the conditions (checks, labels, approvals, frozen sets), the role that may release it, and the reply text.roles: who may fire which event: repository permission, a named set frozen at an earlier event, an author-kind, a bot.agents: which profile may act in which state, on which backend, with which tool allowlist, and what it may produce; nothing outside this list runs.checks: CI steps a gate requires, emitted as GitHub checks the gate reads.bookkeeping: deterministic effects of human events β open the next tracking issue, post a transition, close the umbrella.labels: the label set reconciled against the repository.
Hive's own lifecycle is expressed in this schema as hive-default by a generator over the existing stage table (labels-and-control-signals/stage-labels.md "The table"). That is the conformance test for the schema: if it cannot express Hive's graph, it is not done.
Store
- Location:
/data/workflows/<name>/<version>.yamlplusindex.json, alongside the other hive-owned data; optionally also committed to the repository under.hive/workflows/when the operator wants the model reviewed as a PR (recommended for the TechDocs case). - API:
GET/POST /api/workflows,GET/PUT/DELETE /api/workflows/{name}/{version},POST /api/workflows/{name}/{version}/compile(returns the compiled profile and diagnostics),POST /api/workflows/ingest(see below). Owner-gated; every write audited (workflow_save,workflow_bind,workflow_unbind). - Binding:
project.workflow: {name, version}inhive.yaml, editable from Settings β Repos. Unbound means built-in. Rebinding takes effect on the next sweep; in-flight items re-derive from facts, so no migration pass is needed, but the monitor shows a one-time "re-derived under " note. - Export/import: a single-file bundle (model + compiled profile + checksum) is the unit the marketplace will publish. Import verifies the checksum and recompiles locally; nothing published is trusted as compiled.
Ingest
POST /api/workflows/ingest with a source descriptor; the dashboard offers the same from a button in Settings β Repos and from the viewer.
| Source | What is read | What is proposed |
|---|---|---|
| GitHub Actions | .github/workflows/*.yml: triggers, jobs, needs: graph, required checks, environments with reviewers |
checks and gates; environment reviewers become roles; job order becomes state order |
| Tekton / OpenShift Pipelines | Pipeline, PipelineRun, Task CRDs from a repo path or a cluster context; runAfter, when, finally |
states from tasks, gates from when, terminal from finally |
| Issue templates and labels | .github/ISSUE_TEMPLATE/*.yml, label set, settings.yml |
intake event, label vocabulary, triage states |
| Branch rules | required reviews, required checks, code owners | gates and roles on the merge transition |
| Written spec | a Markdown document with a lifecycle section | an LLM-assisted proposal, clearly marked as inferred, every element citing the paragraph it came from |
Ingest produces a draft model with citations, never a bound one. The compiler runs on it; the operator reviews the diagram, fixes the diagnostics, saves, and binds separately. Inferred elements carry confidence: inferred until a human edits or confirms them. This is the October design's "being able to represent is different from being able to infer" rule made concrete.
Visual view and edit
A new dashboard section, Workflows, with:
- Library: saved models and versions, source, bound repositories, Select/Deselect per repository, Export, Duplicate, Delete, Ingest.
- Diagram: states as nodes in their display columns, transitions as edges labelled with the event and gate, roles and agents as badges on the nodes they may act in, "not covered" and compiler diagnostics as red markers. Click a node or edge to edit it in a side panel; the YAML pane updates live and vice versa. Rendering uses the SVG primitives the Lifecycle Timeline already uses; no new drawing dependency.
- Simulate: paste or pick a real issue/PR and see which state the model puts it in and why, using the same
Factsthe engine would use. This is the operator's confidence check before binding. - Diff: two versions side by side, as diagram and as YAML.
hive-defaultopens read-only here so a new operator can see Hive's own lifecycle as a picture.
Activity Monitor columns come from the model
Today the monitor's columns are constants in the dashboard bundle: the path STAGE_TRACKER_PATH = [0, 10, 20, 30, 50, 80] plus a terminal cap column (agent-now.js, tracker-motion.js:466β479), with their names and the stageβcolumn anchoring in tracker-words-core.js. A model cannot change them. This RFC moves that definition into the model:
columns: an ordered list, each withid,label, a shorthint, and the list ofstatesit collects (so several states can share a column, as 050β085 share one today). The terminal column is a column like any other, flaggedterminal: true.hive-defaultcarries the current seven columns and the current stateβcolumn anchoring, generated from today's constants; this is what keeps the v5/v6 monitor pixel-identical for unbound repositories.- The tracker payload (
/api/trackerand the SSE deltas) gains aworkflowblock per repository:{name, version, columns}. The dashboard renders headers and places rows from that block instead of the constants. For an unbound repository the block ishive-default, so the JS has one path, not two. - A repository bound to a different model gets its own column set on the board. When the monitor shows several repositories at once, it groups rows by workflow: one header row per model, repositories under it. Mixed views never try to force one model's states into another's columns.
- Waiting reasons, gate pills and the replies they offer are read from the state the row is in, as declared in the model; the current verbs (
decide:approve,release, β¦) arehive-default's declarations. - Elapsed time per column, the lifecycle timeline and throughput charts key on
column.id, so they work for any model without per-model code.
Changing a bound model's columns re-renders the board on the next payload; no rows are lost because placement is re-derived from facts.
Commands, labels and checks
Generated from the bound model on bind and on every version change:
- Labels reconciled declaratively (create missing, never delete without confirmation).
- Comment commands registered with the command sweep, authorized by the model's roles;
/hive helplists them on that repository. - Checks emitted by a small workflow Hive writes to
.hive/workflows/checks.ymlthrough a PR, not by direct push, so the repository's own review covers it.
Marketplace (v7, out of scope to build now, in scope to not preclude)
The export bundle, the meta block (author, license, source), the checksum and the recompile-on-import rule are what a marketplace needs. The hub gains a catalogue later; publishing is a human act from the library, never automatic.
Non-goals
- Changing the built-in lifecycle or its labels.
- An LLM deciding a state, gate or permission.
- Remote binding from the hub.
- A general BPMN or workflow-engine product; the schema is as small as Hive's consumers need.
- Running the ingested pipeline (Hive does not become a CI engine; it reads pipelines to learn the process).
Phasing
- P1 β Schema, compiler,
hive-defaultgenerator,DeriveFromModelbehindworkflow.enabled: false. Done whenhive-defaultcompiled throughDeriveFromModelpasses the stage goldens byte-for-byte against the built-in derivers. - P2 β Store, API, Settings β Repos binding, audit; tracker payload carries the
workflowblock and the monitor renders columns from it. Done when a hand-written model binds to a test repository and the board shows its column names and state placement, while unbound repositories render pixel-identical to today. - P3 β Workflows section: library + diagram view (read-only) + simulate. Done when
hive-defaultand the TechDocs model render and simulate correctly. - P4 β Visual edit, YAML pane, diff, versioning. Done when the TechDocs model can be changed from the diagram and the change regenerates labels and commands.
- P5 β Ingest: GitHub Actions, issue templates, branch rules. Done when ingesting
cncf/techdocsproposes the intake and triage states with citations. - P6 β Ingest: Tekton / OpenShift Pipelines, written spec. Done when a Tekton pipeline from a cluster context becomes a draft model.
- P7 β Export/import bundle; hub listing. Marketplace publishing is a separate RFC.
Each phase is its own epic with a readiness bar.
Open questions
- Where a repository's model lives by default: hive data dir (operator-owned) or
.hive/workflows/in the repository (reviewable, forkable). Proposal: hive data dir by default, repository when the operator opts in; the TechDocs case opts in. - Whether a model may extend
hive-default(inherit and override a few states) or must be whole. Proposal: whole in P1βP4; inheritance after we have two real models. - How the human-gate pill picks replies when a model defines more than the current verbs.
- Whether a sibling driver on Crux should host the compiler for non-Hive consumers (Spotlights, a docs-assessment service). The compiler and schema are a separate package with no Hive imports so that stays open.
Related
- ADR-0025 central stage engine;
pkg/stageengine(deriver.go,decision.go,reconciler.go,stage_goldens_test.go) labels-and-control-signals/stage-labels.md,maintainer-commands.md(label-driven repositories)- Workflow intake design, 29 Oct 2026 (Andy; attached as a follow-up comment)
- CNCF TechDocs AI-assisted assessment spec (
nate-double-u/cncf-techdocs,ai-assisted-assessment-spec) - [RFC] Archetypes for long-running tasks: name Oracle/Generator/Executor/Gate onto the staged convergence layerΒ #7620 archetypes, [RFC] Govern one external software-factory workflow through Hive's existing admission pathΒ #8201 external workflow admission, π RFC: v7 - Hive for teams (shared sessions, org policy, multi-forge, entitlements, audit)Β #17091 v7 RFC
Activity
clubanderson commentedon Nov 11, 2026
Reference: the 29 Oct 2026 workflow intake design this RFC is the first slice of (inference deferred). Full text below, example model JSON attached inline after it.
workflow-intake-design-20261029.md
Hive workflow intake: understand the process, then work within it
Design draft, 29 October 2026. No runtime changes or automatic enrollment.
The product
Point Hive at an organization. It discovers the repositories it is allowed to see, studies how work moves through them, and creates a customized process model for each relevant repository, branch, subsystem and kind of work.
People can see that model as a diagram and as text, inspect why Hive created each part, validate it against real activity, and edit it now or later. Once activated, the same model governs the activity tracker, transition gates, work lanes and agent assignments. This is not a choice between a few predefined Hive pipelines.
The distinction that matters: being able to represent a workflow is different from being able to infer every rule from the available evidence. Unwritten decisions, inaccessible rules and opaque external systems must appear as unknown or human-owned, not as rules Hive confidently invents.
An organization scan is permission to observe, not permission to enroll every repository or start agents.
1. One model, several consumers
Use a versioned workflow model: a typed description of states, events, conditions, actors and permitted actions. A compiler validates it and produces a profile that the runtime can evaluate deterministically. The analysis agent proposes the model; it does not become the runtime decision-maker.
Do not let the diagram, scheduler, merge code and agent prompts each interpret repository labels independently. They must consume the same evaluated decision or a traceable adapter to it.
Separate what happened from what Hive would permit next. If an external actor moves work through an unexpected path, reconcile the observed truth and record a deviation or uncertainty. Do not hide a real merge or reject a real event merely because the inferred graph lacked an edge.
The model belongs in Hive's control plane. Crux remains the agent runtime behind its existing boundary; it should not acquire a second implementation of repository governance.
2. What the org-wide intake reads
Start with GitHub organizations, while keeping source adapters separate from the model. GitLab, Gitea, external CI and mail-based contribution need adapters, not a different state engine.
Collectors must record pagination, installation boundaries, unavailable sources, API errors and freshness. A bounded scan can resume with a durable cursor. It must not report "all workflows imported" after silently hitting a page limit.
Do not execute imported Actions, scripts or plugins to analyze them. Resolve supported declarative structures and retain opaque behavior as an explicit external step.
The import pipeline
The organization can delegate routine, non-expanding updates through an approved policy. It should not need to answer the same mapping questions for every repository. New permissions, ambiguous behavior and wider automation require explicit review.
Deterministic where possible; agents where useful
Use both. There is no reason to make a model guess a job dependency that a YAML parser can read exactly. There is also no reason to pretend that every project's process is fully described by a standard config file.
An analysis agent may help collect evidence, not just interpret it. Its tools should return captured, addressable observations; an agent's statement that a rule exists is not itself a verified source fact.
Every proposed rule should carry its evidence references, interpretation, assumptions, open questions and proof category: mechanically verified, source-declared, inferred, or unknown. A confidence score alone must never authorize an action. Another agent agreeing is not a substitute for source validation.
Checking that a citation still contains the quoted text proves the quote's integrity, not the interpretation. Confirming a rule's meaning needs an appropriate semantic extractor, an authoritative structured source, or approval under the organization's policy.
Agents can draft the process graph, explain it, suggest corrections and look for counterexamples. They cannot silently activate a profile or create their own action permissions. Cache by source revision and reanalyze changed or unresolved pieces instead of running a fresh full-org agent survey every time.
Agent interpretation itself need not be deterministic. Capture its candidate output and analyzer/model version as versioned inputs. Replay and compilation consume those saved inputs; they do not call the model again and hope to get the same answer. Reinterpreting unchanged sources creates a new proposal, not an unexplained runtime change.
Give intake agents scoped, read-only collection tools, not publication credentials. Repository content is evidence to analyze, not authority to change the agent's instructions or expand its tool/data scope.
Carry one profile safely across the organization
The proposed control-plane registry stores immutable profile objects and a desired version for each assigned scope. Source capture and analysis must run where the installation's data policy permits; an org-wide feature is not permission to move private enterprise data into a public hub or external model.
Existing repository identity and enrollment remain separate. A profile reference can live beside existing per-repo policy rather than changing
project.reposfrom its current string-list shape or copying an entire graph into every agent definition.Deliver profile versions through the authenticated hub/spoke configuration path, with explicit schema compatibility and acknowledgment. Display desired, applied and executing versions. Unsupported schemas or disconnected owners must be visible, not silently replaced with a guessed legacy process.
There must be one fenced execution owner for a work instance even if multiple hives observe the repository. Work orders carry that ownership generation. Changing the active version invalidates affected permits; an offline or stale owner cannot keep writing under an old policy. Long-running read-only analysis need not be killed merely because authorization changed.
These are rollout requirements to implement and verify, not claims that profile distribution and fencing already exist.
3. The diagram and text are first-class
One definition; two synchronized editors. Neither view is a screenshot or a disposable AI-generated summary.
The initial text format can be YAML backed by a versioned schema, with JSON used for APIs and exports. The visual editor edits the same typed model. Mermaid or UML-style exports are useful views, but a lossy diagram language must not become the authority for gates or permissions.
The accompanying HTML shows a design example with a graph and its JSON definition together. They are generated from the same example record; this demonstrates the intended relationship, not an already implemented visual editor.
What people should see
An unknown gate must look unknown, not like an ordinary waiting job or a successful check. Layout changes and display-label edits should be distinguished from changes to behavior or authority.
Use a split graph/text view with linked selection: selecting a node highlights its definition, and selecting a definition highlights the node. A validation result should point to both. The operational tracker can show a compact live projection; the workflow designer needs the full editable graph, not just another status table.
Editing contract
Visual changes produce typed model patches. Text edits parse into the same model. Both use a revision check so concurrent edits cannot overwrite each other unnoticed.
Saving an invalid draft is acceptable; activating one is not. Validation must identify the offending node, edge, guard or binding. Unsupported future constructs must be shown as opaque/text-only elements rather than silently deleted by the visual editor.
Semantic round trips must preserve state IDs, transition semantics, guards, actor bindings, provenance and human overrides. Formatting need not be byte-identical; comments should be retained by the authoring syntax tree where practical.
Re-import without erasing people's work
Keep three layers:
Re-import is a three-way semantic merge against the previous source snapshot. It preserves human-owned fields and exposes conflicts. It does not regenerate the whole definition and discard edits.
Source-backed constraints are visibly locked in the Hive overlay. Removing a required external check from a diagram cannot remove GitHub's requirement. A future "change the source workflow" feature should generate a separately authorized repository PR, not pretend a local graph edit changed upstream CI.
People can also author genuinely new Hive-owned steps, not just correct an import. Mark these as operator-authored intent rather than discovered repository behavior, and show their effect on lanes and gates before activation.
4. A model that can express different processes
Do not force imported work through today's named Hive stages or roles.
The model needs stable identities for workflows, variants, entities, states, transitions, actors, guards, lanes and action adapters. It should support:
The primitive vocabulary is versioned and finite; the combinations are not a fixed catalog of process templates. New labels, states, lanes and arrangements should be data changes. A previously unsupported external protocol or action may require an adapter.
There are two related graphs:
Process graph: how work moves, who owns each step, and what permits a transition.
Execution graph: jobs, checks and agent tasks associated with a process instance. A matrix job may expand dynamically here without inventing permanent lifecycle states for every matrix value.
Do not flatten GitHub Actions into a single sequence or equate every CI job with an agent lane.
Variant composition is explicit. A PR touching several subsystems may need several ownership or validation regions, not whichever path matched first. Preserve the source system's real ordering and override semantics; intersect applicable authority constraints. If process overlays genuinely conflict, report the conflict rather than silently selecting the more permissive interpretation.
The core records
The example accompanying this design illustrates parallel human review and CI, a repair lane, and a human-owned merge. It is a proposed model shape, not configuration supported by today's Hive.
5. Turning the model into lanes and agent work
A lane is an opportunity to do a defined kind of work while particular conditions hold. It is not just a column in a picture, and not necessarily one permanently running agent.
Each lane needs:
The planner emits a bounded work order containing the profile version, fact revision, repository, entity/head, lane, agent binding and scope of allowed actions. Existing governor and Crux controls still apply.
The proposed dispatch contract needs explicit identifiers for the work instance, profile hash, facts revision, source head/base or merge-group context, lane, registered actor, task contract, authorization reference, claim/lease and expiry. A task instruction is not an authorization token. These are additions to design, not fields already accepted by today's kick API.
Scope identity must include the forge/instance and stable repository identity, not just
owner/name; otherwise identically named public and enterprise repositories can be confused.Gates attach to actions, not to all work globally. Failed CI can block merging while enabling a repair lane. An unavailable release-policy source need not prevent an independently authorized issue-triage observation.
Before any effect, the host rechecks relevant current facts, capability grants, pause/hold status, freshness and the work claim. A stale planning decision is not authority to write. A policy or head change can revoke or invalidate a work order.
Deduplication and leases must survive retries and restarts. Parallel read/review tasks can coexist where allowed; exclusive mutations need an explicit coordination key. Do not promise exactly-once external side effects: use idempotency where supported and reconcile ambiguous outcomes.
Cover every entry point
Today's additive CEL kick routing is not enough to enforce a customized process. Scheduled kicks, event triggers, manual dispatch, resume/retry paths, hooks and autonomous sweeps must all respect the selected profile when working on a profile-managed scope.
The enforcement inventory must also cover API relays, PR creation, merge paths and the git push broker, not just the visible scheduler. For an enforced scope, an unbound agent prompt cannot be a shortcut around a missing or expired work permit. Explicit operator-directed exceptions need their own authorized, audited contract.
Keep the legacy/default behavior unchanged for scopes that have not opted in. Do not enable profile enforcement until the relevant entry points and effects have contract coverage; merely adding another candidate-agent list alongside native routing would not satisfy this design.
Example behavior
An accepted issue enables an implementation lane. Opening its PR activates parallel human review and CI. A failing check enables the authorized repair lane without satisfying the merge gate. A new head invalidates evidence that is head-bound. Once all required conditions are satisfied, the tracker shows Ready for maintainer. It does not create an agent-owned merge lane unless that authority already exists and is approved for the repository.
Approval freshness is policy-specific: do not universally dismiss reviews that a repository intentionally carries forward. But never reuse an old review as Hive's trusted exact-head override for a new head.
6. Keep process inference separate from authority
The analysis system may infer what a label seems to mean. It must not infer that a bot is trusted, that an agent may merge, or that a repository wants automated participation.
Effective authority is the intersection of existing platform controls, organization grants, repository/branch policy, the action's guard and the actor's current capabilities. Repository rules may tighten that envelope; an inferred profile cannot widen it.
Use existing ACMM, pauses, holds, budgets, provenance and audited mutation boundaries. Do not create a second bypass path in the workflow engine.
Important details:
LLM analysis is advisory and inspectable. Runtime decisions use the compiled definition and facts, not a fresh model opinion.
Process readiness and actor permission are different outputs. "Ready for maintainer" can correctly coexist with "this agent may not merge." Show the actor and action being evaluated; never treat a displayed stage or label as a capability grant.
7. Fit this into Hive rather than build a parallel product
The following are existing seams, not claims that workflow intake is already implemented. Runtime source was inspected in the readability worktree at commit
8f73a3d212f8c7ec9cc7c1e325e674f848cc229e; semantic search was used for discovery, not as proof of the current implementation.The survey independently inspected tracker/stage code at
878554651e538376bfe4d157786027ba165a581a. Its verified integration points are the central decision, single writer, fact sink, non-blocking transition-anomaly check, tracker data/SSE projection and diagram/map consistency test.Status matters: the central stage architecture is implemented, but the arbitrary-profile interpreter and compound-state editor are not. External workflow admission is partially shipped as a default-off, report-only pilot; publication remains a separate undecided gate. Gate-integrity regression automation is a proposal, not existing enforcement. The design must not depend on an unshipped safeguard.
The workflow engine should begin in the Hive module, outside Crux. Keep source adapters, the model/compiler, evaluation and projections separated by small interfaces. Package names and API paths below are proposals, not existing APIs:
Generalize the existing stage authority; do not add another writer
The companion survey verified
stageengine,stagelabels, the tracker response/SSE surface, and the existing diagram/transition-table consistency test as the relevant integration points. Implementing this design will still require checking those contracts against the then-current branch.The intended migration is:
The existing fixed stage vocabulary is not an arbitrary-workflow schema. Imported state IDs should be internal, stable and profile-scoped, not automatically published as a new set of GitHub labels. A legacy summary is a compatibility projection only where it is truthful; it must never become a shortcut around the full action gates.
The existing Mermaid diagram and Go transition map being cross-checked is useful precedent for keeping views honest. It is not yet a canonical model that generates both views. Likewise, existing tracker data/rendering can be reused without claiming the current component already implements a compound-state visual editor.
8. Validation before activation
Validation needs to answer more than "does the YAML parse?"
Model checks: references resolve, actor bindings exist, guard types are valid, required variants are covered, parallel joins are explicit, terminal/blocked states are explainable and prohibited actions cannot be reached. Legitimate rework loops are allowed; task execution still has bounded retries and resource limits.
Evidence checks: rules retain provenance; observed habits do not become mandatory or optional policy without justification; unavailable policy stays unknown.
Replay: use pinned workflow/configuration fixtures and event traces, with snapshot reconciliation where history is incomplete. Test duplicate and reordered deliveries, dismissed approvals, new heads, merge queues, changed requirements, skipped jobs, matrices, reusable workflows, retries and cancelled runs.
Round trips: graph to model to text to model preserves behavior; text-only constructs survive graphical edits; re-import preserves human corrections; concurrent edits produce an explicit conflict.
Shared decisions: tracker explanations, lane eligibility and effect authorization refer to the same decision context and versions. Tests must catch contradictory interpretations while preserving legitimate distinctions such as human readiness versus denied agent permission.
Shadow mode: compare proposed eligibility with actual authoritative outcomes and investigate differences. Do not treat agreement with historical behavior as proof that historical behavior was authorized.
Rollout: opt-in profiles, canary scopes, visible drift, revocable work permits and a rollback path that does not relax current external requirements.
A schema-valid profile with unresolved evidence can be active in observe mode. Enforcement is action-scoped: relevant required conditions must be known and satisfied, and the actor must already be authorized. Unknown release policy should not stop an unrelated, permitted read-only triage task. This avoids turning incomplete understanding of an organization into a blanket demand to hand-configure every repository.
No collected private configuration, credentials or sensitive process data should be sent to a third-party analysis service without the organization's explicit authorization. Analysis backends must follow the installation's data-handling policy.
The graph, textual definition, evidence inspector and exports inherit repository visibility rules. A convenient org overview must not expose private repository names, policy details or credentials to a viewer who could not access the underlying scope.
9. Staged delivery
A week-sized prototype could demonstrate the first two stages on a bounded, authorized sample. "Every workflow in the world" is a long-term compatibility target, not a credible one-week production guarantee.
Suggested implementation cuts
These are dependency-oriented cuts, not an instruction to open all PRs at once. Live execution depends on the enforcement cut, not just on completing the editor.
Acceptance bar
A new repository should get its own source-backed process shape, not a renamed Hive preset. A person should be able to inspect both graph and text, identify an uncertain inference, correct it once, see the effect on gates and lanes, replay the change, and retain that correction on the next import. Later activation must make the tracker, scheduler and permitted agent effects agree.
Open design work
These are design tasks, not authorization to change production or open implementation PRs.
Appendix: what the project survey changes about this design
The companion survey inspected eight representative projects. This is a bounded public-source study, not a verified snapshot of each project's effective live permissions or deployed service configuration.
This supports a source graph, not a YAML-only importer. It also supports distinct approval semantics: native review, owner coverage, trusted bot decision and human action are not interchangeable.
Public-file visibility is not the product's visibility ceiling. A connected installation should query authorized branch-protection/ruleset and provider APIs. What cannot be read remains explicitly unknown; it is not evidence that required checks are structurally undiscoverable or that every repository must always be manually configured.
James's Gemini share transcripts were not retrievable with the survey's tools and were not used as evidence.
workflow-intake-example-20261029.json (illustrative, not runnable)
{ "apiVersion": "workflow.hivecommons.dev/v1alpha1", "kind": "IllustrativeWorkflowDraft", "metadata": { "name": "issue-to-maintainer-merge", "status": "design-example-not-activated" }, "spec": { "scope": { "repository": "example/project", "workType": "issue-fix" }, "sourceSnapshot": "illustrative-source-snapshot", "authority": "existing-grants-only", "initial": "triage", "states": [ { "id": "triage", "label": "Maintainer triage", "owner": "human" }, { "id": "implement", "label": "Implementation", "owner": "registered-agent" }, { "id": "verify", "label": "Parallel verification", "type": "parallel", "regions": [ { "id": "review", "label": "Human review", "owner": "human", "guardRef": "review-policy-satisfied" }, { "id": "ci", "label": "Required CI", "owner": "external-service", "guardRef": "required-checks-satisfied" } ], "completion": { "allRegionsSatisfied": true, "unknownBlocksCompletion": true } }, { "id": "ready", "label": "Ready for maintainer", "owner": "human" }, { "id": "done", "label": "Merged", "type": "final", "owner": "external-observation" } ], "guards": [ { "id": "accepted-by-maintainer", "sourceRef": "trusted-repository-triage-policy" }, { "id": "review-policy-satisfied", "sourceRef": "effective-current-review-policy" }, { "id": "required-checks-satisfied", "sourceRef": "effective-required-check-policy" } ], "transitions": [ { "id": "accepted", "from": "triage", "to": "implement", "guardRef": "accepted-by-maintainer", "label": "accepted" }, { "id": "pr-opened", "from": "implement", "to": "verify", "event": "linked-pr.opened", "label": "PR opened" }, { "id": "verified", "from": "verify", "to": "ready", "event": "parallel-regions.satisfied", "label": "both satisfied" }, { "id": "rework", "from": "verify", "to": "implement", "event": "review.changes-requested", "label": "changes requested" }, { "id": "eligibility-changed", "from": "ready", "to": "verify", "event": "eligibility.invalidated", "label": "head or policy changed" }, { "id": "merged", "from": "ready", "to": "done", "event": "provider.pr-merged", "label": "maintainer merges" } ], "lanes": [ { "id": "implement-fix", "activeIn": ["implement"], "actorRef": "configured-agent:fixer", "actionRef": "existing-authorized-pr-proposal" }, { "id": "repair-ci", "activeIn": ["verify"], "when": "required-ci-failed", "actorRef": "configured-agent:ci-maintainer", "actionRef": "existing-authorized-pr-repair" } ], "gateSemantics": { "recheckOnRelevantFactChanges": true, "reopenReadinessOnRevocation": true, "invalidateOnlyEvidenceBoundToChangedRevision": true }, "notes": [ "Illustrative, incomplete design fixture; not runnable Hive configuration.", "Approval, provider identity, head freshness and capability policies must be resolved from trusted sources before activation.", "This example has no agent-owned merge action.", "Layout is presentation metadata, not process semantics." ] } }github-actions commentedon Nov 11, 2026
Hi @clubanderson! To assign yourself, use the slash command:
/assign(and/unassignto remove).Resources: Contributors Guide
π roadmap: add v7 and workflow-models RFCs under Later (#17626)
clubanderson commentedon Nov 11, 2026
Phase-1 proving survey: CNCF landscape + Tekton
Code: #17630 (
pkg/workflowmodel, v6). Corpus: everycncf/landscapeproject tagged sandbox / incubating / graduated / archived β primary + additional repos (262 projects β 299 repos), plus 18 Tekton / OpenShift Pipelines repos (tektoncd/, openshift-pipelines/, konflux-ci/*, openshift-knative, shipwright). Per repo: one tree listing, fetch.github/workflows/*.y*ml,.tekton/**, and any YAML whose head iskind: Pipeline|PipelineRun|Task. Collector is reproducible (collect.py, ~8 min).The 35 unparsed files are honest failures: Jinja-templated samples in tektoncd/catalog and openshift/pipelines-tutorial,
.mdfiles under.tekton/, and one malformed workflow (drasi-project).Constructs (how much of the real world the model has to carry)
needs4,399 Β·if3,193 Β· matrix 1,558 (dynamicfromJSON327; include/exclude 472) Β· reusable-workflow nodes 1,521 Β· concurrency 1,045 (140 expression-valued) Β·environment153 Β· path filters 983 Β·merge_group168 Β·pull_request_target256 Β·workflow_run111 Β· Tekton tasks 1,298 Β·finally110 Β·when385 Β· PaCon-cel-expression30.Activity Monitor column sets
Deploy: release-beta-images βΊ release-helm βΊ release-tool βΊ renovate, envoyDeploy: pypi, radiusDeploy: publish-de-image, loxilbDeploy: production βΊ Deploy: releaseThe CI / Review column gains sub-stages from the repo's own PR-verify DAG (merged topological levels, capped at six). argo-cd:
stateDiagram-v2 [*] --> open state "Open (human)" as open state "Actionable (human)" as actionable state "Claimed (agent)" as claimed state "PR in progress (agent)" as pr_in_progress state "CI / Review (ci)" as verify state verify { state "Review (human)" as review -- state "CI (ci)" as ci note right of ci Auto Assign PR Author: assign-author Cherry Pick: find-labels β cherry-pick Integration tests: changes Β· shellcheck β build-go Β· build-ui Β· check-go +4 β test-e2e Β· test-go Β· test-go-race β analyze Β· test-e2e-composite-result Code scanning - action: CodeQL-Build Image: set-vars β build-and-publish Β· build-only β Deploy Β· build-and-publish-provenance Lint PR: validate GitHub Actions Security Analysis: zizmor end note } state "Merge queue (ci)" as merge_queue state "Merged" as merged state "Main CI (ci)" as main_ci note right of main_ci Integration tests: changes Β· shellcheck β build-go Β· build-ui Β· check-go +4 β test-e2e Β· test-go Β· test-go-race β analyze Β· test-e2e-composite-result Code scanning - action: CodeQL-Build Image: set-vars β build-and-publish Β· build-only β Deploy Β· build-and-publish-provenance Scorecards supply-chain security: analysis GitHub Actions Security Analysis: zizmor end note state "Release (ci)" as release note right of release Publish ArgoCD Release: setup-variables β argocd-image β argocd-image-provenance β goreleaser β generate-sbom Β· goreleaser-provenance β post-release Β· sbom-provenance end note state "Done" as done done --> [*] open --> actionable: triaged actionable --> claimed: claimed claimed --> pr_in_progress: pr-opened pr_in_progress --> verify: ready-for-review verify --> merge_queue: verified [required-checks-satisfied] merge_queue --> merged: merged merged --> main_ci: pipeline-succeeded main_ci --> release: pipeline-succeeded release --> done: pipeline-succeededkonflux-ci (Pipelines-as-Code: pull-request and push runs share
build-pipeline, so one Tekton pipeline binds to both CI / Review and Main CI; 18 tasks over 7 levels):stateDiagram-v2 [*] --> open state "Open (human)" as open state "Actionable (human)" as actionable state "Claimed (agent)" as claimed state "PR in progress (agent)" as pr_in_progress state "CI / Review (ci)" as verify state verify { state "Review (human)" as review -- state "CI (ci)" as ci note right of ci Verify Caddyfile formatting: caddy-fmt Check for README updates: check-toc Differential ShellCheck: lint fullsend: dispatch Β· review-denied Β· stop-fix Static code checks: kube-linter Operator Lint: check-changes β lint Operator OLM Kind Smoke: check-changes β olm-kind-smoke Operator E2E Tests: check-prerequisites β check-changes β test Β· test-skip β report-operator-e2e-status Operator Tests: check-changes β test Verify Generated Operator Files: check-changes β verify-generated Deploy to GitHub Pages: build-docs Β· deploy Renovate manifest companion PR: companion Test Changelog Generator: test-changelog Validate AGENTS.md file: check-length Verify rendered manifests in sync: check-changes β verify-manifests build-pipeline: init β clone-repository β prefetch-dependencies β build-images β build-image-index β apply-tags Β· build-source-image Β· clamav-scan +9 β sast-coverity-check end note } state "Merge queue (ci)" as merge_queue state "Merged" as merged state "Main CI (ci)" as main_ci note right of main_ci Operator Tests: check-changes β test Deploy to GitHub Pages: build-docs Β· deploy build-pipeline: init β clone-repository β prefetch-dependencies β build-images β build-image-index β apply-tags Β· build-source-image Β· clamav-scan +9 β sast-coverity-check end note state "Release (ci)" as release note right of release Community Operator PR: create-pr end note state "Done" as done done --> [*] open --> actionable: triaged actionable --> claimed: claimed claimed --> pr_in_progress: pr-opened pr_in_progress --> verify: ready-for-review verify --> merge_queue: verified [required-checks-satisfied] merge_queue --> merged: merged merged --> main_ci: pipeline-succeeded main_ci --> release: pipeline-succeeded release --> done: pipeline-succeededFindings (reported, never guessed)
secrets-inherit462 Β·reusable-only378 (callable workflows; the caller carries the role) Β·no-trigger227 (bare TektonPipelinelibrary files) Β·job-container154 Β·concurrency-expression140 Β·task-definitions89 Β·finally68 Β·environment-on-pr49 Β·on-error45 Β·not-tekton29 Β·yaml-parse6 Β·environment-dynamic2 Β·custom-task2.Noisiest repos: llm-d (128
secrets-inherit), cilium (100 pipelines; 21 PR-verify workflows declare environments), tektoncd/pipeline and konflux-ci/release-service-catalog (Tekton libraries with no trigger β correct, nothing to bind).What the survey changed in the code
_stale.ymlvsstale.ymlcollided after slugging βDedupeIDs.environment:β single Deploy column +environment-dynamicfinding, instead of a column named${{ β¦ }}.on: [pull_request, push]β CI / Review and Main CI); tags-only pushes bind to Release only.pipelineRefmerge into one pipeline with deduped triggers; non-YAML files under.tekton/skipped.Gaps for phase 2
kubernetes/*, ~28 repos) is a third syntax; those render the default columns.pull_request_target-only bots (labelers, welcome, stale) classify as pr-verify and inflate CI level 0 (cilium L0 = 29 nodes). The editor is where a maintainer deselects them; a heuristic (noneeds, single job,actions/labeler-style) could pre-deselect.celevents, not classified β konflux'starget_branch.matches("refs/tags/β¦")push run should add Release.HiveDefaultand renders today's seven columns β that is the compat promise phase 2 must keep.Fixtures from six repos (argo-cd, cilium, envoy, konflux-ci, tektoncd/pipeline, serverless-operator) pin these results as goldens in #17630.
clubanderson commentedon Nov 11, 2026
P1 report β schema, compiler, hive-default, DeriveFromModel
PR: #17639 (stacked on #17630).
Decision recorded:
hive-defaultderivation stays in Go. The model is generated fromstagelabels.Table+stageengine.DiagramEdges()+ the monitor's column anchors and declaresderivation: builtin;DeriveFromModeldelegates to the existing derivers and only checks coverage. Custom models usederivation: rules(ordered first-match predicates over a fixed fact vocabulary; uncovered βworkflow: not covered). No second state machine, no LLM in derivation.Bar (goldens byte-for-byte): met.
TestDeriveFromModelHiveDefaultParityruns the entire PR stage-golden corpus plus an issue sweep through both derivers and requires identicalDecisions.hive-default compiled: 7 columns, 23 states, ~70 transitions, 0 diagnostics.
Compiler refusals implemented (one test case each):
state-no-exit,gate-no-owner,agent-no-human-gate,duplicate-event-fact,state-no-column,unknown-column,duplicate-stage-number,unknown-fact,bad-op,no-rules,no-version,bad-derivation-mode,unknown-state/role/gate/event,column-empty,no-terminal-column. One relaxation from the RFC text: a closure edge (item closed unmerged) out of an agent-granted state is an observation, not an outcome the agent can bring about, so it does not count as a gate-free path β otherwisehive-defaultitself refuses (every stage has a closure edge). A merge edge out of an agent state without a human gate still refuses (TestCompileClosureEdgesAreNotAgentPaths).Reference custom model:
testdata/models/techdocs.jsonβ the cncf/techdocs engagement (Requested β Analysing β Analysis review β² β Drafting β Draft review β² β Approved β Published), two human roles, two gates, two agent grants, 9 rules. Compiles clean; the rules evaluator walks it end to end.Flag:
workflow.enabled(default false). Nothing changes for any hive in P1.Next (P2): store under the data dir,
/api/workflows,project.workflow_bindings, trackerworkflowsblock, engine wiring for bound repos.β¨ workflowmodel: phase-1 ingest (GitHub Actions, Tekton), renderers aβ¦
β¨ workflowmodel: store, /api/workflows, repo bindings (RFC #17620 P2a)
β¨ stageengine: per-repo workflow binding, tracker workflows block (RFC β¦
workflow models P2: Settings/tracker UI, openapi, gates, docs (P2c)
clubanderson commentedon Nov 11, 2026
Phase 2 report β store, API, bindings, engine wiring, tracker columns
PRs: P1 β #17648 (re-opened against v6; #17639 was auto-closed when #17630's branch was deleted on merge), P2 β #17649 (stacked on #17648).
Built
pkg/workflowmodel/storeβ versioned on-disk library,hive-defaultvirtual, drafts allowed but not bindable. Reservedadoption/ratings/benchmarkson every entry (for the marketplace + rate/vote/benchmark work later; carried verbatim, no migration needed).project.workflow_bindingsβ per-repo{repo, name, version}; live reload; bind refused for non-compiling models; delete refused while bound./api/workflowsfamily (list/save/read/delete/compile/bindings), owner-gated, audited, in OpenAPI.Options.WorkflowFor+DeriveForRepo; bound repos βDeriveFromModel, everything else β builtin derivers byte-identical. Gated byworkflow.enabled(default off).workflowsblock + JS (model column header, per-row strip, "Not covered" chevron); Settings β Repos per-repo Workflow select.Proof: store 92.4% coverage; API/engine/UI harness tests; all dashboard gates (OpenAPI coverage, import ratchet, settings parity, CSS tokens) green; lint clean; P1 parity corpus unchanged.
Next (P3): ingest β lifecycle half, so the 317 surveyed CNCF pipelines produce draft models with provenance
ingested-unreviewed; reruncmd/workflow-survey, compile every model, report compile pass/refusal table here.96 remaining items
β¨ marketplace: seed curated models and ship the CNCF TechDocs assessmβ¦
github-actions commentedon Nov 12, 2026
PR #17798 has merged (#17798) and referenced this issue with a non-closing
Refs #17620rather than a closing keyword.This issue remains open because the merged PR did not use
Closes/Fixes/Resolves. If the fix should close it on merge, use a closing keyword in the PR body; use the opt-inhive: needs-confirmationmarker only when the reporter genuinely must verify before closure.chore: move changelog fragment to root changelog.d/
chore: move changelog fragment to root changelog.d/
β¨ workflows: owner toggle for model-based stage derivation from the dβ¦
docs: resync api-reference citations drifted on v6
β¨ [v6] workflows: owner toggle for model-based stage derivation from β¦
π± Top up v6 with v5 latest (v5.237.2) (#18030)
π marketplace: resume CNCF catalogue seeding across hub restarts and β¦
π marketplace: stream repository tarballs and keep only pipeline files (
β¨ marketplace: seed curated models and ship the CNCF TechDocs assessmβ¦
β¨ workflows: owner toggle for model-based stage derivation from the dβ¦
clubanderson commentedon Nov 16, 2026
Implemented on v5 and v6 in #17679, #17681, #17688, #17685, #17706, #17710, #17708, #17713, #17714 (v6 via top-up #17747). Remaining gaps are tracked in #18354 (engine writes model state labels, do first), #18356 (post-merge pipeline status), #18357 (model verbs on PRs and un-parked issues), #18355 (checks.yml emission). Closing as completed.