Skip to content

πŸ“ RFC: Workflow models β€” ingest, store, edit and select a repository's workflow without changing the built-in oneΒ #17620

Closed

Description

@clubanderson

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, branch ai-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

  1. 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.
  2. One engine, one writer. Models plug in as a third Deriver implementation (DeriveFromModel) behind the existing Deriver interface (deriver.go:6) and produce the existing Decision (decision.go:10); the Reconciler stays the only label writer. No second state machine.
  3. 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.
  4. 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.
  5. 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 the stage/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 a fact the engine already has or a new one the ingester adds to Facts.
  • 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>.yaml plus index.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} in hive.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 Facts the engine would use. This is the operator's confidence check before binding.
  • Diff: two versions side by side, as diagram and as YAML.
  • hive-default opens 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 with id, label, a short hint, and the list of states it collects (so several states can share a column, as 050–085 share one today). The terminal column is a column like any other, flagged terminal: true.
  • hive-default carries 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/tracker and the SSE deltas) gains a workflow block 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 is hive-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, …) are hive-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 help lists them on that repository.
  • Checks emitted by a small workflow Hive writes to .hive/workflows/checks.yml through 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-default generator, DeriveFromModel behind workflow.enabled: false. Done when hive-default compiled through DeriveFromModel passes the stage goldens byte-for-byte against the built-in derivers.
  • P2 β€” Store, API, Settings β†’ Repos binding, audit; tracker payload carries the workflow block 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-default and 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/techdocs proposes 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

Activity

  1. added
    area/coreIssues or PRs related to core changes
    kind/designCreated by Hive for agent-filed issue provenance
    proposalRFC / design proposal for discussion
    on Nov 11, 2026
  2. clubanderson commented on Nov 11, 2026

    @clubanderson
    MemberAuthor

    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.

    Consumer What it gets from the compiled model
    Activity tracker Current states, parallel branches, waiting reasons, ownership and next eligible transitions
    Gates The conditions and evidence required for a particular action, with an explicit allow, deny or unknown result
    Lane planner Work that is useful and authorized in the current state; claims, dependencies, limits and stop conditions
    Agent dispatch A bounded work order, bound to a registered agent, repository, work item and permitted action
    Mutation boundary A fresh authorization and gate check before a side effect, not merely a prompt saying what is allowed
    Evidence and explanation The same decision trace the other consumers used, including source facts and model version

    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.

    Evidence What it can tell Hive Important limit
    Repository inventory and App installation scope Which repositories exist within the authorized view; archived/fork status and default branches Installation coverage is not necessarily the whole organization
    Actions files and referenced reusable workflows Events, job dependencies, conditions, matrices, concurrency and external calls A job graph is not the whole contribution process
    Branch protection and repository/org rulesets Enforced merge requirements and branch-specific policy Some policy needs additional read permissions; missing access is not an empty rule set
    Labels, bot configuration and command handlers Triage decisions, holds, ownership, approval signals and automation conventions A label's name alone proves neither its meaning nor who may apply it
    CONTRIBUTING, AGENTS, CODEOWNERS and process docs Human roles, execution restrictions, review conventions and subsystem variants Natural-language interpretation is a proposal unless bound to trusted policy
    Check runs, commit statuses, reviews and timelines What actually happens, on which head, by which actor or provider Observed habit is evidence, not proof that an omitted gate is optional
    Environments, release configuration and external systems Deployment approvals, release flow and non-Actions stages CI, approval and deployment ownership may live outside GitHub

    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

    1. Discover: inventory the authorized organization and repository scopes.
    2. Capture: save an immutable, permission-scoped evidence snapshot, with source revisions and coverage.
    3. Analyze: extract explicit rules first; use analysis to propose relationships, meanings and missing pieces.
    4. Compile: check references, guards, actor bindings, parallelism and authorization constraints.
    5. Preview: show the inferred graph, text, provenance, uncertainty and effect of proposed edits.
    6. Replay and shadow: compare the proposed behavior with recorded events and current authoritative facts, without side effects.
    7. Activate: publish a validated profile within the owner's existing grants.
    8. Reconcile: ingest events and policy changes; create explainable revisions rather than silently rewriting the active process.

    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.

    Work Preferred approach
    Inventory, pagination, source snapshots, hashes and source locations Deterministic collectors
    Supported workflow syntax, declared dependencies, rulesets and provider statuses Deterministic parsing and normalization
    Discovering nonstandard process sources and following relevant references A read-only agent using scoped collector tools
    Understanding contribution docs, custom bots, scripts and the relationship between labels and human decisions Agent-assisted interpretation producing cited candidate rules
    Reference/type checks, policy composition, semantic diffs, replay and compilation Deterministic validation
    Runtime state, gate results, lane eligibility and permitted effects Deterministic evaluation of the activated model and current facts

    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.repos from 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

    • Org overview: repository/process coverage and variants, not one unreadable graph containing the entire organization.
    • Workflow view: composite states, parallel branches, conditions, timers, loops, ownership and human/external/agent swimlanes.
    • Text view: the actual editable definition, validation errors and stable state/transition IDs.
    • Inspector: source file or rule, source revision, observation time, confidence, authoritative owner and the reason for a state or gate.
    • Execution overlay: actual events, current head, checks, agents, time spent waiting and the precise reason an action is blocked.
    • Version view: generated candidate, edited draft, active version, semantic diff and replay results.

    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:

    1. Source evidence: what the repository and services currently say.
    2. Generated proposal: Hive's interpretation, with evidence and uncertainty.
    3. Human overlay: accepted corrections, additional rules, agent bindings and layout.

    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:

    • Hierarchical and parallel states; conjunctions and alternatives; events, timers and human decisions.
    • Rework loops, cancellation, retries, explicit dependencies and terminal outcomes.
    • Issue, PR, release, deployment and other supported work types.
    • Branch, path/subsystem, author-class and repository-specific variants.
    • External systems whose state Hive observes but does not control.
    • Cross-repository dependencies only where supported by explicit evidence and authorized access.

    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

    Record Purpose
    Evidence snapshot Sources, permissions, revisions, observation times, completeness and extracted facts
    Workflow definition Typed process, variants, conditions and intended bindings
    Human overlay Corrections and customizations kept across imports
    Compiled profile Validated semantics, source references, compiler version and immutable content hash
    Work instance Repository/entity identity, active profile version, current facts, head and execution history
    Decision Allow/deny/unknown, reasons, dependencies, facts revision and policy version
    Work order and permit Bounded task, registered actor, allowed effects, work claim, expiry and cancellation conditions

    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:

    • An eligibility condition and explicit work-item scope.
    • An actor binding: human, external service, or registered Hive agent.
    • An action contract, allowed effects and applicable execution restrictions.
    • Dependencies, claim/lease behavior, budget and concurrency limits.
    • A completion condition, timeout, retry policy and escalation path.

    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:

    • Bind checks to the expected provider/App, repository, head or merge-group context and run attempt, not just a matching green name.
    • Treat cancellation, missing checks, failed collection and unknown policy distinctly. Preserve the source provider's actual skip/neutral rules.
    • Read trusted base-branch process definitions; a PR changing its own workflow or policy cannot authorize itself.
    • Model human approvals as human-owned where required. AI review must not quietly substitute for them.
    • Imported code or natural-language instructions cannot register privileged actions. Reuse vetted action adapters and audited APIs.
    • Tightening requirements can immediately restrict affected actions. Removing a gate or adding authority needs an approved widening policy or explicit review.
    • Rollback of a Hive profile cannot undo a new external restriction. Fresh external policy remains authoritative.

    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.

    Existing seam Reuse Gap for this design
    InstallationCoverage Permission-scoped installation inventory and explicit truncation It caps its coverage check at ten pages; it is not an org-wide workflow collector
    GitHubActivityFeed.listRepos Existing paginated org discovery pattern A process inventory needs source capture, completeness, branch/ruleset data and resumable reconciliation
    ProjectConfig and RepoPolicy Repository identity, pause, per-repo policy, forge and label-driven customization Arbitrary workflow/profile bindings and variants are additional data, not another hardcoded policy flag
    TriggerRule and HookRule Fail-closed CEL expressions and operator-owned, vetted transition actions Additive kick triggers and a closed transition catalog are not yet a general workflow state model
    celtrigger integration Typed event routing and deduplicated agent candidates A compiled workflow must carry state, work identity, evidence and action eligibility
    Governor.AgentEligibleForCELKick Preserve pause, budget, on-demand and kick-channel checks A matched rule is only a candidate; also validate the registered actor and task-specific authorization
    crux.Runtime Lifecycle, observation, kicks and agent definitions through an established boundary Current kick methods accept prompts, not the complete typed workflow work-order contract
    cruxhost capability callbacks Host-provided policy, scoped services and mutation capabilities Bind proposed work permits to the existing host/effect boundary rather than adding an unaudited executor

    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:

    workflow/sources     -> immutable evidence, source coverage, normalized events
    workflow/model      -> versioned typed definitions and human overlays
    workflow/compile    -> validated profiles and semantic diffs
    central stage seam  -> shared facts-to-process-decision authority
    workflow/project    -> tracker views and candidate work orders from that decision
    existing governor   -> scheduling limits and actor eligibility
    existing gates/host -> actor authorization, fresh preflight and enforced effects
    Crux runtime        -> bounded dispatch through the existing boundary
    

    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:

    1. Keep the existing default process and its behavior unchanged.
    2. Extend the central fact/derivation seam to select a legacy deriver or a compiled-profile interpreter for a work instance. Do not have two authorities derive competing process states for the same work key.
    3. Keep controlled stage-label writes behind the existing writer. A visual edit or agent interpretation is never a direct label writer.
    4. Add profile identity, current nodes/regions, reasons and evidence coverage to the tracker's existing data/event contract in a compatible, versioned way.
    5. Connect task proposals and action preflights to that shared context, without confusing a process decision with authorization.

    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

    Stage Useful outcome What stays out
    Read and draw Authorized org inventory, evidence snapshots, inferred graph and text, source/unknown inspector No enrollment or agent side effects
    Validate and edit Shared typed editor model, overlays, semantic diff, fixture replay and version history No silent activation
    Drive the tracker Profile-backed state/explanation projection alongside a compatibility view for existing stages No independent new gate interpretation
    Drive gates and lanes The same evaluated model proposes work and checks actions through existing enforcement seams No removal of ACMM or authorization checks
    Operate and learn Opt-in bounded work orders, drift handling, broader source adapters and reusable discovered patterns No claim that every external protocol is automatically understood

    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

    1. Evidence records, permission-scoped inventory and source adapters, with no enrollment.
    2. Typed model/compiler and a legacy-process compatibility fixture.
    3. Draft/version API and synchronized graph/text authoring with provenance.
    4. Shadow profile evaluation feeding the existing tracker data/event seam.
    5. Shared action-gate integration and an exhaustive dispatch/effect-entry-point inventory.
    6. Opt-in bounded lane work orders, permits and fenced rollout.
    7. Additional provider adapters and expanded real-project compatibility fixtures.

    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

    • Specify the migration from the pinned tracker/stage contracts to the then-current implementation branch.
    • Specify the minimal versioned schema, provider event envelope and action/permit integration contract.
    • Choose visual-editor technology after measuring the current tracker component's reuse potential.
    • Set org-owner approval/delegation rules and private-data analysis policy before live intake.
    • Select the first consented org/repositories and capture fixtures without starting agents.

    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.

    Project Observed shape worth accommodating Design consequence
    Home Assistant Integration/path-aware ownership and change-selected CI Support subsystem scope and computed execution plans; do not infer enforced review policy from CODEOWNERS alone
    Kubernetes Hierarchical ownership with Prow/Tide configuration outside the application repository Follow authorized cross-repository process sources; distinguish labels, bot decisions and owner coverage
    Linux Mail, trailers and maintainer trees rather than a GitHub PR pipeline Represent human/external processes; add mail/tree adapters where supported instead of inventing GitHub states
    Rust Bot-managed queues and dynamically generated CI plans Queue authority and dynamic jobs are explicit, provider-specific model elements
    CPython Bot-managed process labels and reusable CI workflows Preserve who owns a label and what consumes it; do not substitute a similarly named Hive signal
    VS Code Change detection, reusable workflows and an aggregate PR check Model computed fan-out and aggregate gates; a check name alone does not prove it is required
    LLVM Contribution policy and external CI references spread across sources Keep service-owned checks and prose-declared requirements distinct from API-confirmed effective policy
    Airflow Declarative infrastructure policy plus programmatic selective checks Capture both declared configuration and computed plans; reconcile declaration with deployed rules where authorized

    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."
        ]
      }
    }
  3. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 11, 2026
  4. github-actions commented on Nov 11, 2026

    @github-actions
    Contributor

    Hi @clubanderson! To assign yourself, use the slash command: /assign (and /unassign to remove).

    Resources: Contributors Guide

  5. clubanderson commented on Nov 11, 2026

    @clubanderson
    MemberAuthor

    Phase-1 proving survey: CNCF landscape + Tekton

    Code: #17630 (pkg/workflowmodel, v6). Corpus: every cncf/landscape project 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 is kind: Pipeline|PipelineRun|Task. Collector is reproducible (collect.py, ~8 min).

    Repositories 317 (299 with GitHub Actions pipelines, 17 with Tekton)
    Files read / parsed 4,523 / 4,488 (99.2%)
    Pipelines 4,389 β€” pr-verify 1,792 Β· push-verify 430 Β· release 315 Β· deploy 42 Β· scheduled 638 Β· manual 272 Β· other 900
    Models valid 317 / 317
    Repos whose Activity Monitor columns change 296
    By maturity graduated 61 Β· incubating 38 Β· sandbox 173 Β· archived 27 Β· Tekton extras 18

    The 35 unparsed files are honest failures: Jinja-templated samples in tektoncd/catalog and openshift/pipelines-tutorial, .md files under .tekton/, and one malformed workflow (drasi-project).

    Constructs (how much of the real world the model has to carry)

    needs 4,399 Β· if 3,193 Β· matrix 1,558 (dynamic fromJSON 327; include/exclude 472) Β· reusable-workflow nodes 1,521 Β· concurrency 1,045 (140 expression-valued) Β· environment 153 Β· path filters 983 Β· merge_group 168 Β· pull_request_target 256 Β· workflow_run 111 Β· Tekton tasks 1,298 Β· finally 110 Β· when 385 Β· PaC on-cel-expression 30.

    Activity Monitor column sets

    Repos Columns
    203 Open β€Ί Actionable β€Ί Claimed β€Ί PR in progress β€Ί CI / Review β€Ί Merge queue β€Ί Merged β€Ί Main CI β€Ί Release β€Ί Done
    65 … β€Ί Merged β€Ί Main CI β€Ί Done
    28 today's seven, unchanged (Prow-based repos such as kubernetes/kubernetes, repos with only bots/schedules)
    21 one or more Deploy: <env> columns, e.g. cilium Deploy: release-beta-images β€Ί release-helm β€Ί release-tool β€Ί renovate, envoy Deploy: pypi, radius Deploy: publish-de-image, loxilb Deploy: production β€Ί Deploy: release

    The 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-succeeded
    
    Loading

    konflux-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-succeeded
    
    Loading

    Findings (reported, never guessed)

    secrets-inherit 462 Β· reusable-only 378 (callable workflows; the caller carries the role) Β· no-trigger 227 (bare Tekton Pipeline library files) Β· job-container 154 Β· concurrency-expression 140 Β· task-definitions 89 Β· finally 68 Β· environment-on-pr 49 Β· on-error 45 Β· not-tekton 29 Β· yaml-parse 6 Β· environment-dynamic 2 Β· custom-task 2.

    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

    • IDs: _stale.yml vs stale.yml collided after slugging β†’ DedupeIDs.
    • Expression-valued environment: β†’ single Deploy column + environment-dynamic finding, instead of a column named ${{ … }}.
    • A workflow with several triggers binds to every role they imply (on: [pull_request, push] β†’ CI / Review and Main CI); tags-only pushes bind to Release only.
    • Tekton: PipelineRuns sharing a pipelineRef merge into one pipeline with deduped triggers; non-YAML files under .tekton/ skipped.

    Gaps for phase 2

    1. Prow (kubernetes/*, ~28 repos) is a third syntax; those render the default columns.
    2. 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 (no needs, single job, actions/labeler-style) could pre-deselect.
    3. PaC CEL triggers are kept as cel events, not classified β€” konflux's target_branch.matches("refs/tags/…") push run should add Release.
    4. Bare Tekton libraries (catalogs) bind nowhere until a PipelineRun or Trigger references them.
    5. Nothing is wired into the stage engine; a model with zero pipelines hashes identical to HiveDefault and 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.

  6. clubanderson commented on Nov 11, 2026

    @clubanderson
    MemberAuthor

    P1 report β€” schema, compiler, hive-default, DeriveFromModel

    PR: #17639 (stacked on #17630).

    Decision recorded: hive-default derivation stays in Go. The model is generated from stagelabels.Table + stageengine.DiagramEdges() + the monitor's column anchors and declares derivation: builtin; DeriveFromModel delegates to the existing derivers and only checks coverage. Custom models use derivation: 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. TestDeriveFromModelHiveDefaultParity runs the entire PR stage-golden corpus plus an issue sweep through both derivers and requires identical Decisions.

    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 β€” otherwise hive-default itself 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, tracker workflows block, engine wiring for bound repos.

  7. clubanderson commented on Nov 11, 2026

    @clubanderson
    MemberAuthor

    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-default virtual, drafts allowed but not bindable. Reserved adoption/ratings/benchmarks on 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/workflows family (list/save/read/delete/compile/bindings), owner-gated, audited, in OpenAPI.
    • Engine: Options.WorkflowFor + DeriveForRepo; bound repos β†’ DeriveFromModel, everything else β†’ builtin derivers byte-identical. Gated by workflow.enabled (default off).
    • Tracker workflows block + 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; rerun cmd/workflow-survey, compile every model, report compile pass/refusal table here.

  8. 96 remaining items

  9. github-actions commented on Nov 12, 2026

    @github-actions
    Contributor

    PR #17798 has merged (#17798) and referenced this issue with a non-closing Refs #17620 rather 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-in hive: needs-confirmation marker only when the reporter genuinely must verify before closure.

  10. clubanderson commented on Nov 16, 2026

    @clubanderson
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/coreIssues or PRs related to core changeshelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.kind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions