Curation & change management

Concept governance defines the model — authority tiers, lifecycle, provenance. This page covers the surfaces where the work happens: a workspace Curationpage with the change-request queue and the review-due list, governance actions and revision history on every entity's detail panel, and a Glean-style verification badge on every document. Everything here is also scriptable — see the API walkthrough.

The Curation page

Knowledge → Curationis the steward's home screen. Summary cards up top show the workspace's governance posture at a glance — concepts by authority tier, open change requests, overdue reviews — with two working tabs beneath:

• Change requests — the open queue: kind, target concept, proposer, age, and a payload summary, with Approve/Reject actions (each takes an optional review note) and a history sub-tab of resolved requests.
• Review due — stale concepts whose next_review_at has passed, most overdue first, with inline Mark reviewed and Certify actions.

Change requests

Change requests are the gated track of two-track gating: instead of editing a governed concept directly, anyone can proposea change and let the concept's reviewers decide. Five kinds exist, each with a validated payload:

• create — propose a new concept (name, type, optional aliases/description). Approval creates it at authority curated, lifecycle published — it was just reviewed by definition.
• update — propose edits to name, type, aliases, or description. Approval applies them and promotes authority to at least curated (never demoting a certified concept).
• deprecate / supersede — retire a concept from active guidance, optionally naming a live, published successor.
• delete — propose removal (soft delete, with a final revision recorded first).

A request is open until it is approved, rejected (reviewer, with note), or withdrawn (proposer). Approval applies the change atomically and stamps the resulting revision's activity as change_request:<id>, so history shows which approval produced every change.

In the UI, the entity form dialog has a "Submit as change request" toggle — same form, gated path — and the queue lives on the Curation page. Over the API it is POST /api/v1/change-requests plus /approve · /reject · /withdraw.

The review-due queue

Every certification or review stamps the concept's next review date (now + reviewIntervalDays, default 180 — configurable in workspace settings). When the date passes, the concept enters the Review due tab, and the drift scan keeps a single deduplicated curation.review_overdue alert open until the queue is empty. Two inline actions clear an entry:

• Mark reviewed — restamps the review clock; if the concept was still machine_extracted, the review promotes it to curated.
• Certify — owner/admin sign-off to certified, the only tier assistants state without hedging.

Entity governance panel

The entity detail panel wears the governance state on its sleeve: an authority badge (certified = emerald, curated = blue, asserted = slate, machine-extracted = neutral outline), a lifecycle badge when not published (draft = amber, pending review = violet, deprecated = red, superseded = red with a strikethrough and a link to the successor), the owner and stewards, and a provenance line — v4 · reviewed 12d ago · review due Jan 14. Source references (label + optional URL) list where a definition came from, and the steward-only editorial note is visible here and nowhere else.

The actions menu carries the full curation verb set:

• Certify and Mark reviewed — the review-due actions, available anywhere.
• Set authority… — explicit tier set, including demotion when trust was misplaced.
• Assign owner… — owner plus steward list; this also determines who reviews change requests.
• Deprecate… / Supersede… — with an entity search picker for the successor.
• Edit refs…, Edit editorial note…, Save as draft / Publish.

Revision history

Below the panel's metadata sits the append-only revision log — every version of the concept, newest first: the change kind, version number, actor, age, optional note, and an expandable field-level diff ({ field: { from, to } }). Because each row also snapshots the full concept and records the PROV-O activity that produced it, "who changed this definition, when, and through what mechanism" is always one glance away:

{
  "version": 4,
  "changeKind": "certify",
  "activity": "ui",
  "changedBy": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
  "note": "Confirmed with the payments team",
  "diff": { "authority": { "from": "curated", "to": "certified" } },
  "createdAt": "2026-07-14T10:02:11.000Z"
}

Revisions and audit rows are never updated or deleted; the log survives even entity deletion (the final delete revision is written first). Fetch it programmatically with GET /api/v1/entities/{id}/revisions.

Document verification

Documents get the same treatment as concepts, following Glean's verification model. Every document carries a verification state — unverified (default), verified, certified, or deprecated — shown as a badge on the document view header and as an icon in list rows. The Verify… action stamps who verified it and when, and schedules re-verification on the same workspace review interval; expiry surfaces it for re-review rather than silently trusting stale pages. Setting unverified or deprecated clears the stamps.