← Governed Agentic Empirical Research
How agentic-governance works
The workflow inside, and where the human comes in
agentic-governance is the operating system my repositories run on. It says how work is planned, classified, done, reviewed, merged and remembered, whether a person or an AI agent does it. The short version: agents can do almost all of the work. A human approves every change that alters meaning.
Describes v0.9.1 at commit 01c7d69. This page is a summary. Where it and the canonical documents disagree, the documents win.
Three layers
- Canon. One repository holds the policy, stated once: the operating system, the governance levels, the role charters, the Definition of Done, the review checklist and the templates. It knows nothing about any particular project.
- The delta. Each adopting repository carries one file,
llm/governance/governance-delta.md. It binds the canon to that project: mission, design-authority document, the paths it uses, its check command, its L0 allowlist, what its platform can actually enforce, and whether the steward lane is switched on. It also pins the canon version, so a repository upgrades on purpose and never by accident. - Execution. A Claude Code plugin supplies four AI role agents, three skills (
/governance:establish,/governance:audit,/governance:migrate) and a dependency-free checker,governance-checks.mjs. Specialist analysis is handed to the separate Constellize personas rather than duplicated.
The repository itself is split by role. Anything that governs, plans or records how the repository runs lives in llm/, the control plane. Deliverables, external material and generated views such as this page live in docs/ or on a site, the data plane, and each view has to name the control-plane document it summarizes (ADR-0001).
The workflow
Every piece of work takes the same path, whatever produced it. Nothing skips review except an explicitly authorized emergency repair.
project-operating-system.md §Core Workflow and architecture-governance.md §PR Lifecycle.Two rules hold the workflow together. A semantic change has to exist as a pull request before anyone can review it, so opening the draft PR is the author's job, not the owner's. And no decision counts if it lives only in a chat, a prompt or a meeting note, including a conversation with an AI assistant. It has to land in the repository as an ADR, a design update, a memory-bank entry, or an issue or PR note before anyone acts on it.
Every change gets a level
Before merge, each change is classified at exactly one of four levels. The level decides who reviews it and who may merge it. A change is semantic if a reasonable reviewer could believe it alters meaning, behaviour, decisions or obligations. The burden of proof sits on the non-semantic side: if deciding needs judgment, the change is semantic.
| Level | What it covers | Review | Who merges |
|---|---|---|---|
| L0 Administrative | Fourteen closed categories of bookkeeping: memory-bank sync to merged work, checkbox progress, ADR status flips citing the approving PR, index regeneration, link repair, formatting, narrowly defined typos, branch cleanup. | Steward certification plus an independent audit | The Repository Steward, only where the repo has activated the fast track. Otherwise the human owner. |
| L1 Governance and architecture | ADR content, the design-authority document, architecture, domain model, governance policy, the delta itself. | Human review required, against the review checklist and Definition of Done | The human owner only. No AI role, in any mode or team size. |
| L2 Implementation | Code, schemas, migrations, APIs, auth, infrastructure, CI/CD behaviour, executable configuration. | ||
| L3 Product | Requirements, scope, personas, business rules, user-visible behaviour, privacy and consent, prioritization. |
- Uncertain means semantic. If anyone is unsure, the change goes to human review at the lowest plausible semantic level.
- Mixed changes take the highest level. One L1 sentence in a bookkeeping PR makes the whole PR L1, which is why authors split housekeeping out.
- Escalation runs one way for AI. Any participant may move a change up. Only the human owner may move it down, and only by saying so on the PR or issue.
Who does what
| Role | Kind | Responsible for |
|---|---|---|
| Project owner | Human | Final decisions, sole merge authority above L0, branch protection and repository administration, resolving agent and classification disputes, deciding whether the steward lane is ever activated. |
| Chief Architect | AI role | Architectural coherence. Classifies the work and picks the execution mode before substantial work starts, and records both on the issue or PR. |
| Chief Reviewer | AI role | Review quality and decision integrity for L1–L3 work. Also serves as the Governance Auditor for the L0 lane. |
| Chief Product Officer | AI role | User value and scope discipline. |
| Repository Steward | AI role | The L0 lane: certifies, opens and, only where activated and after independent audit, merges narrow bookkeeping PRs. The one exception to "no AI role merges its own work". |
| Specialists | AI or human | Scoped workstreams under a bounded contract, usually Constellize personas. They classify their own work and default to semantic when unsure. |
Authoring, reviewing and merging stay separate responsibilities. In a solo project one person can wear more than one hat, but for semantic work the author never reviews their own change and the reviewer never merges it. Every agent starts from a bounded contract that lists its role, objective, required reading, allowed and forbidden files, deliverables, Definition of Done, the boundary of what the work is not, and who commits. Its handoff must state assumptions, alternatives, risks, open questions and ADR candidates.
Execution modes
The Chief Architect picks one of three modes for how the work is produced: a single agent on one bounded contract; a team of specialists with disjoint file scopes followed by a reconciliation round; or a dependency-aware orchestration that launches agents in waves and runs an independent governance audit. The mode never changes what review the work needs. Work produced by a many-agent orchestration still goes through Issue, Branch and PR, and a human still merges it.
The L0 fast track
The only lane where an AI merges anything is for L0 bookkeeping, and it ships switched off. Turning it on takes a repo-local ADR plus an activation PR that a human approves and merges. Turning it off takes a human statement and a flip of the delta back to INACTIVE.
l0-fast-track.md §Ordered Artifact Chain and §Per-Repo Activation.A PR qualifies only if all twelve conditions hold. Among them: every line is non-semantic, no code, schema, behavioural configuration, ADR content or design-authority text changes, any ADR status flip cites the merged PR that approved it, the checks pass, the auditor records PASS, and no review thread is left open. The checker reads the allowlist from origin/main, never from the PR's own tree, so an L0 PR cannot rewrite the rules that judge it. An auditor's rejection is final for the lane, and the steward may not re-certify the same diff.
Where the human comes in
This is the part people ask about most. The table lists every point in the canon where a human decides, and whether anything can stand in for them.
| When | What the human does | Can an AI do it? |
|---|---|---|
| Adopting a repo | Runs /governance:establish, approves each GitHub-remote change it proposes (creating the remote, branch protection), and accepts the new plugin marketplace in a later session. | No. Accepting a marketplace has no non-interactive path, and the skill reports it as a required human follow-up. |
| Every semantic PR | Reviews the result against the checklist (with the Chief Reviewer's review in hand) and merges it. | No. Sole merge authority for L1–L3. |
| Durable decisions | Approves or rejects ADRs and design-authority changes. | Agents draft and recommend; they do not accept. |
| Classification | Moves a change to a lower level, and settles any dispute about level. | AI may only escalate. Until the human rules, the change is treated as semantic. |
| Agent disagreements | Resolves conflicts the design-authority document and ADRs don't settle, then records the decision. | No. |
| The L0 lane | Writes or approves the activation ADR, merges the activation PR, and can switch the lane off at any time. | No. Adoption never grants it. |
| Layout migration | Reviews and merges the PR that /governance:migrate opens to move pre-v0.3 content. | The skill does the moves; the merge is human. |
| Stale branches | Decides whether to delete branches the audit lists. | The audit reports only. A branch with no PR is never deleted, because it may be the only copy. |
| Repository settings | Branch protection and repository administration. | No. |
What the human does not have to do: the bookkeeping. Where the fast track is active, memory-bank syncs, checkbox progress and index regeneration merge without them, under certification and an audit trail. Where it is inactive, which is the default, the same certification and audit still get produced as review aids, but they authorize nothing.
What code checks, and what rests on judgment
The canon is unusually frank about this, and each adopting delta has to restate it for its own platform.
Checked mechanically
- Changed paths fall inside the L0 allowlist and outside the always-denied set (the delta, policy docs, code, scripts,
.github/). - Diff shapes match their constraint: status line only, index rows only, checkbox flips only, link targets only.
- The certification block is present in the PR body.
- Every path the delta declares exists (
--layout). - The audit skill's twelve checks, including whether anything actually runs the check command automatically, and whether it is a required status check.
Resting on people and discipline
- Whether a change really preserves meaning. The semantic test is judgment.
- Whether a cited PR really approved the decision an ADR flip records.
- Whether a link fix kept pointing at the same document.
- Whether the auditor's session was really independent of the steward's.
- Ordering of the artifact chain, unless the platform blocks an early merge.
- Anything a repo's platform can't gate, such as role separation under one shared token.
Not built yet
Four gaps are on record in the canon itself. None of them is solved by this page.
- Checks are wired but not required (G-2).
establishadds the check to CI but doesn't make it a required status check, so a red PR can still merge. Since v0.9.1 the audit reports this, but the setup step doesn't close it. - Outcomes aren't verified (G-3, specified 2026-09-18). The canon governs process thoroughly and outcomes hardly at all. An acceptance criterion is an anonymous checkbox, and an agent can tick it on its own evidence. The spec adds claim identifiers, verification states bound to the exact wording, and a rule that an agent's own assertion can never reach "human verified".
- Model choice is invisible (G-1). Which model ran a piece of work is never declared or recorded.
- It is bound to one harness. The execution layer is a Claude Code plugin. The 2026-10-01 audit maps what has to separate so that Claude Code, OpenCode, Codex or CI run the same protocol. Implementation hasn't started.
Sources, all at commit 01c7d69:project-operating-system.md,governance-levels.md,architecture-governance.md,l0-fast-track.md,BACKLOG.md,harness-independence audit.