Skip to main content
Driftless governs understanding the way GitHub governs code. A topic isn’t “the truth” the moment someone writes it. It becomes Knowledge only once an owner or admin merges it in. That one distinction is what lets an agent trust the context it receives, instead of reading from a wiki that quietly rots.

​
Everything is one topic that evolves

There’s one primitive, a topic, and it matures along a single trust axis: Note → Knowledge. A Note is a draft (private by default; share it to the workspace and it’s Up for review). Knowledge is the team’s source of truth: a note becomes knowledge once it’s merged in. Merging is an owner/admin act. An owner or admin can merge it themselves, or explicitly ask an agent to run the merge on their behalf, same authority either way. To change existing Knowledge you open a Suggested edit, which an owner or admin merges. 
Note  →  Up for review  →  Knowledge     (+ Archived)
(draft)    (proposed)      (reviewed)
  • Note: a draft or private observation. Only you see it; it’s excluded from search; untouched notes auto-archive after ~14 days (recoverable). Think here. Share it to the workspace and it’s Up for review.
  • Up for review: a Note put up for human review. It’s awaiting a merge, lives in the review queue, and can be sent back with a reason.
  • Knowledge: the team’s source of truth, the notes merged in. An owner or admin’s authority added it to knowledge, so it joins the team’s living, code-anchored knowledge graph, the multi-context map of the whole codebase. This is the durable truth an agent consumes.
reviewed topics carry governance.authoritative: true + approved_by/approved_at + approved_via (human if a person merged it, agent if an agent ran the merge on an owner/admin’s request). Internally the status enum stays draft/proposed/reviewed/archived; the names above are the product language. The model is simple: agents propose; merging into Knowledge is an owner/admin act. approve, reject, and merge require owner/admin authority. An ownerless agent key or a non-owner can write notes but is refused the merge. An agent can run the merge, but only when an owner or admin explicitly asks it to, never on its own initiative. 
driftless context propose <slug>     # Note → Up for review
driftless context approve <slug>     # add to knowledge (merge it in)
driftless context reject <slug> --reason "..."   # → back to a Note (with feedback)
driftless context archive <slug>     # retire it

​
Three surfaces

The dashboard mirrors the three stages: Knowledge (the Knowledge graph, merged-in notes only), Review queue (the merge/reject queue plus re-review of drifted context), and Notes (your private workspace, with share controls and “expiring soon”).

​
Who can merge: workspace roles

Merge authority is a workspace role. Each member carries one:
RoleCan
memberRead + put notes up for review
admin / owner…+ merge: add to knowledge, reject, archive, and clear drift
Merging a note into Knowledge (and re-confirming a drifted topic) requires the admin or owner role. A member puts notes up for review but does not merge them in. The role is the authority; an agent acting on an owner or admin’s explicit request runs the merge under that authority (and it’s stamped approved_via: agent). Only an owner can grant or revoke the owner role, and the last owner can’t be demoted or removed. The workspace creator is the first owner; manage roles in Settings → Members. Permissions gate merging and visibility only, never coding. Driftless informs; it never blocks a developer from writing code.

​
The trust signal

The whole point of approval is that the agent can tell truth from hint. Every context get carries it in the canonical response: 
{
  "classification": { "status": "reviewed" },
  "governance": { "reviewed": true, "approved_by": "u_cto", "approved_at": "..." }
}
An agent should consume reviewed topics (Knowledge) as truth and draft/proposed ones (Notes) as suggestions. Governance without the agent consuming this signal would just be a wiki.

​
Suggested edit: changing the team’s source of truth

Don’t overwrite a Knowledge topic. To change the team’s source of truth, open a Suggested edit: a proposed content change that a human reviews and merges in. 
driftless context pr <slug>                                     # list open Suggested edits
driftless context pr <slug> --open --summary "why" --content @new.md
driftless context pr <slug> --merge <id>                        # merge it in (owner/admin)
driftless context pr <slug> --reject <id>                       # close without merging
A Suggested edit carries a content patch (whitelisted to content fields, so it can never forge approval). Merging applies the patch and makes the topic Knowledge again, attributed to whoever merged it.

​
Why deterministic

Merging is an owner/admin act, and everything around it is deterministic and auditable: who merged what, when, on whose authority (approved_by), by which hand (approved_via: a person or an agent they asked), and what changed (version + history). A CTO governing context can always answer “why did the agent trust this?” with a precise record, not a model’s guess.
In a future release, platform agents (drift, freshness) will open Suggested edits automatically. They plug into the same review queue, and an owner/admin still decides what merges. The authoring of intelligent Suggested edits is the only piece that waits.