Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

CNCF TechDocs AI-assisted assessment — curated workflow model

cncf-techdocs-assessment@curated-2026.11.2 is the current version of the first curated model in the hub marketplace (https://hive.hivecommons.dev → Settings → Workflows → Marketplace on any hive); curated-2026.11.1 stays in the catalogue unchanged. It encodes the CNCF TechDocs team’s AI-assisted documentation assessment process so a hive bound to cncf/techdocs runs intake, drafting, verification, stakeholder review and approval as a visible lifecycle, with every agent action followed by a human gate.

Source of truth (the model cites both by SHA in its workflow.hivecommons.dev/source* annotations and in each element’s citations):

• Specification: specs/ai-assisted-techdocs-assessment-spec.md at nate-double-u/cncf-techdocs@882be6fef28794433bc3a6a34ac1401391c1d3e4.
• Intake template: .github/ISSUE_TEMPLATE/assessment-request.yml at nate-double-u/cncf-techdocs@ad915303f9774b9aa6b7646969897fada7975a00.
• Checks and labels: the cncf/techdocs .github tree (format, link and spell-check workflows; settings.yml labels), as snapshotted in pkg/workflowmodel/ingest/testdata/techdocs/.

The model’s scope is github.com cncf/techdocs — the upstream repository where the process runs; the fork above is where the spec was written. Model files: pkg/hub/marketplace/curated/cncf-techdocs-assessment-2026.11.2.yaml (current) and pkg/hub/marketplace/curated/cncf-techdocs-assessment.yaml (curated-2026.11.1) (apiVersion: workflow.hivecommons.dev/v1alpha1, derivation.mode: rules, meta.provenance: curated). Curated files are never edited in place: a change is a new file with a new meta.version, and the catalogue keeps every version. The same repository is also in the ingest corpus (pkg/workflowmodel/ingest/corpus/extra.json), so an ingested-unreviewed version built from the pipeline files alone sits next to this one in the catalogue.

How the spec maps onto the model

The spec (§5 Lifecycle, §6 Phases, §12 Lifecycle bindings) describes one six-step loop — request → accept → draft → review → stakeholder review → merge — run once per phase (A analysis, B implementation plan, C issue backlog). The model encodes the loop once and carries the phase as a label (phase/assessment, phase/implementation, phase/backlog; skip-implementation makes the A merge open C). Each phase’s tracking issue and the intake issue itself travel the issue states; each AI-drafted deliverable is a pull request that travels the PR states.

Columns

States and rules (first match wins)

Issues (intake and per-phase tracking issues):

Pull requests (deliverables carry the Docs analysis label; anything else abstains):

Transitions

Every gate is released by a human role; the two agent profiles (techdocs-drafter in accepted/drafting, techdocs-verifier in drafting) can only move work up to a gate, never through one — the compiler’s agent-no-human-gate refusal enforces this.

Roles

Labels

From settings.yml: Docs analysis. Proposed for the assessment: needs-triage, triage/accepted, triage/declined, phase/assessment, phase/implementation, phase/backlog, verified, confirmed, skip-implementation.

Checks

Required CI: format-check, link-check, spell-check (the three cncf/techdocs workflows, ingested as pipelines with their source hashes). Required manual: provenance block present and the strict check passes (spec §15).

Intake

assessment-request.yml fields map to facts as recorded in the workflow.hivecommons.dev/intake-fields annotation: project name, maturity and moving-levels → assessment metadata; website/docs/repo/other-scope/out-of-scope → scope; domains → the agent’s egress allowlist; contacts → the frozen stakeholder set (validated at /accept); tooling/context → drafter input; the HC-6 disclosure acknowledgement is required.

Reference repos from the request

curated-2026.11.2 adds a spec.intake block (hivecommons/hive#18139):

intake:
  referenceRepoFields:
    - "Website or documentation repository"
    - "Other repositories or sites in scope"
  outOfScopeFields:
    - "Out of scope"

The entries are the rendered ### <label> headings of assessment-request.yml as they appear in a request issue’s body, not the form’s field ids. A hive bound to this version derives one write-tier (issues+prs) project.reference_repos entry per repository named under a referenceRepoFields heading and not under an outOfScopeFields heading, once a maintainer with write access to cncf/techdocs applies triage/accepted to the request. The derived entries carry the request as provenance (cncf/techdocs#395 style), are rebuilt on every config load and never written to the overlay or runtime config, and disappear when the issue closes or the label is removed. curated-2026.11.1 is unchanged and declares no intake fields, so a hive that stays bound to it derives nothing.

Operator walkthrough: the Hive Commons pilot

The first request through this path is cncf/techdocs#395, the Hive Commons assessment. What the operator of the TechDocs hive (authorized repo cncf/techdocs) does and sees:

1. Rebind to 11.2. Settings → Workflows → Marketplace, bind cncf/techdocs to cncf-techdocs-assessment@curated-2026.11.2. This step is required: a hive still bound to curated-2026.11.1 derives nothing, however many requests are accepted. No reference_repos entry is written by hand.
2. A maintainer accepts the request. Someone with write access to cncf/techdocs applies triage/accepted to #395. A label applied by a bot grants nothing.
3. Three derived entries appear on the next pass (boot, config reload or every HIVE_REFERENCE_REPOS_DERIVE_INTERVAL, default 10m): hivecommons/docs, hivecommons/hivecommons.github.io and hivecommons/hive, each at the issues+prs tier with derived_from: cncf/techdocs#395. The kick’s 📚 REFERENCE REPOS block lists them with (from cncf/techdocs#395). Settings → Reference repos shows them read-only with the source link and credential_state: write-tier, because hivecommons has the App installed on every repo. Had it not, the entries would read read-only with a reason, #395 would carry one hive:reference-repos-read-only comment, and the hive would keep running.
4. What the hive may do there. Clone and read the three repos, read their issues and PRs, open an issue, open a PR or push a topic branch, and comment on an issue or PR it opened itself. The assessment deliverable still lives in cncf/techdocs.
5. What it may not do. Merge, push to a default branch, label or assign other people’s items, review, or close other people’s issues. The proxy refuses each of these and logs reference_repo in the violations log. hivecommons repos get no queue, no ACMM evaluation and no work items.
6. Closing #395 removes them. When the request issue closes, or triage/accepted is removed, the three entries, their proxy policies and their kick lines are gone on the next pass. Nothing was ever written to the overlay or runtime config, so there is nothing to clean up. A hand-written entry for one of the repos, if the operator adds one, takes precedence and stays.

Not representable today

These parts of the spec are documented in the model’s annotations but not enforced by the engine:

• Close reason (completed vs. not planned) — no fact distinguishes them.
• Approver independence from the drafter and reviewer — no fact records who drafted or reviewed.
• Phase as a state dimension and the A→C skip — carried by labels; the open-next-phase-tracking-issue, notify-contacts and mention-stakeholders bookkeeping actions are declarative only.
• /verify dispatching the verifier agent and membership of the frozen stakeholder set — the gates exist, the side effects do not yet.
• Data-collection scripts and the strict provenance check — a manual check.