UAI Agent Governance Protocol vNext
Binding agent contract — modular wipe/rebuild governance including no-local-copies rule.
Body
UAI Agent Governance Protocol vNext
Status: binding agent contract (lab SOT; public must match)
Date: 2026-07-04 (fable-owned impress pass — journey-first)
Audience: AI agents and operators on any UAI lane
Canonical catalog slug (join): uai-doc-governance- + uai-agent-protocol vnext
Entry journey (join): uai-doc-governance- + agent-journey-bootstrap-to-done
This document is the agent-operable governance contract for modular wipe/rebuild. On conflict with older Explorer-only text (CT121/CT126-only topology, stale version notes, soft “prefer” language), this protocol wins for ecosystem placement, authority, wipe posture, and project work.
Older primary_context docs remain valid for Explorer AI-lane mechanics (redaction, denied surfaces, feedback API). They do not define host placement or wipe authority.
A. Read before acting (agent journey)
Do not mutate anything until this section is satisfied.
Full walkthrough: catalog slug join uai-doc-governance- + agent-journey-bootstrap-to-done.
| Gate | Rule |
|---|---|
| Redaction first | Server-side redaction is mandatory. MUST NOT paste secrets/tokens/keys/private paths into catalog, feedback, diary, plan, or evidence. Write-time 422 is a stop, not a puzzle to bypass. Agents use GET /api/ai/context/{slug} (redacted packets), not HTML views as authority. |
| Permissions | AI PAT may use only bootstrap-listed AI endpoints. Denied: admin, raw FS, uploads, SQLite, .env, .ssh, survey zones, arbitrary path search. Tag ACL must cover document required_tags. |
| Catalog-only | Context HTTP 200 = published policy. Live hosts = facts only. Mac archives = preserve only. Feedback = signal only until promoted. MUST NOT hoard local mirrors of catalog, runtime DBs, or product data — read via API. |
| Promote path | propose → sandbox verify → evidence → lab → public → breadcrumb → verify context 200. No silent binding-rule edits. |
| Sandbox stop | KEEP sandboxes (CT123/124/126…). MUST stop when done. MUST NOT destroy or idle-run. Explorer UI work: CT126 first, CT121 when solid. |
| Infra roles | VPS = Beacon+UAI Thaladex P0; NUC = Cadence home; Lab = Explorer SOT + KEEP sandboxes; Mac = files only (mac_hosting=never; no local data hoarding). |
Session pattern (short): ready → bootstrap → journey → this protocol → primary_context → capability-map → plan → execute → evidence → promote → stop sandboxes → feedback → done.
0. Hard stop conditions (abort immediately)
Stop work and report the blocker. Do not improvise around these.
- Owner stage checkbox missing for any destroy/wipe/recommission stage.
- Stage 0 incomplete (CT103 off-host archive, governance publish, VPS CLI carbon-copy or proven excludes) and the task is wipe-adjacent.
- Request would host a product runtime on Mac (
mac_hosting=never). - Request would destroy a sandbox CT (KEEP — stop only; see §5).
- Request would leave a sandbox running idle after work (MUST stop when done).
- Request would revive CT103 or auto-load legacy Cortex memory into new Cortex.
- Request would open public MX/25, mesh-next cutover, or B70-dependent plans without owner reopen.
- Secrets, tokens, private keys, or private paths would enter catalog, feedback, diary, or receipt.
- Capability card missing for a host/service you are about to mutate — abort; feedback
missing-context. - Lab and public disagree on a binding governance slug at wipe-approval time — reconcile before claiming SOT.
- Required primary_context inaccessible due to missing tags — stop; do not invent access.
- Temptation to use a denied surface “for a legitimate reason” — it is not legitimate; stop.
- Request would clone, mirror, or hoard doc trees, databases, product data, or ecosystem state on Mac/agent workspace — no local copies (§13). Authorized: handoff receipts, START_HERE entry, owner preserve paths per runbook.
1. Authority layers (highest → lowest)
| Layer | What it is | Agent rule |
|---|---|---|
| 1. Owner decisions | Dated owner handoffs / decision notes | MUST obey. Overrides everything below. |
| 2. Explorer published SOT | Catalog docs with context HTTP 200 (this protocol, journey, rules, runbooks, capability cards) | MUST treat as published policy. Lab is write-SOT; public is lagging mirror until promoted. |
| 3. Live hosts | Process up/down, ports, deploy paths on VPS / NUC / lab CTs | Facts only (is it running?). MUST NOT treat live placement as policy when it contradicts layers 1–2 (example: VPS Cadence live = drift, not home). |
| 4. Active plans | Scoped, time-bound intent | Authority only within stated gates and expiry. |
| 5. Mac archives | Off-host preserves, Obsidian, handoff receipts | Preserve/evidence only. MUST NOT treat archives as runtime home, as license to host on Mac, or as agent working mirrors to hoard catalog/runtime data. |
| 6. Feedback | Product feedback API | Signal only. Never a rule until promoted into catalog and context 200. |
Conflict rule: If (1) and (2) disagree → (1) is truth, (2) is stale; promote reconciliation. Never silently pick.
Active-work rule: Local handoffs/Obsidian may be newer during active work. Prefer newest owner-dated decision; promote durable truth to lab, then public, before claiming SOT.
Live-vs-policy rule: “It is running on host X” is not “it belongs on host X.”
Archive-vs-policy rule: “It is preserved on Mac” is not “run it on Mac.” MUST NOT bulk-copy preserved material into agent workspace as a working SOT mirror.
No-local-copies rule: Explorer published catalog is read via GET /api/ai/context/{slug}. MUST NOT scrape, clone, or hoard duplicate doc trees, databases, product data, or ecosystem state on Mac/agent disks. Runtime data lives on designated hosts (VPS, NUC, lab CTs). If persistence is needed, use Explorer feedback or a designated remote path — not ad-hoc local caches.
2. Document kinds (when + anti-patterns)
| Kind | Authority | When | Anti-pattern |
|---|---|---|---|
| runbook | High — another agent must reproduce exactly | Repeatable procedure | Diary-as-runbook; runbook that invents wipe targets |
| plan | Scoped / time-bound | Forward intent with gates and done_when | Plan that pretends to be owner approval |
| evidence | Proves a claim | Receipts, probes, digests (pointers in catalog) | Evidence without what was proven; secrets in body |
| diary | Lineage only | Dated narrative | Citing diary as authority |
| feedback | Signal only | Friction / missing-context / QoL | Treating feedback as a rule; duplicate spam |
Pick rule: Reproduce exactly? → runbook. Forward intent? → plan. Did it happen? → evidence (+ optional diary). Should something change? → feedback, then promote if it becomes rule.
3. Agent session pattern
- Ready probe — require ready, public_safe_mode, server-side redaction, no raw survey mount.
- Bootstrap — follow denied surfaces, stop conditions, and primary_context for Explorer mechanics.
- Read agent journey (redaction, permissions, catalog-only, promote, sandbox stop, infra roles).
- Read this protocol (binding for ecosystem/wipe).
- Read capability-map for the lane; abort if card missing for a mutation target.
- Read owner standing priorities (§6) and post-wipe order (§7) when work is wipe-adjacent or multi-host.
- Write a plan with Product, Task, Authority, Done when — or refuse if authority is insufficient.
- Execute only on the correct host/sandbox. Mac = files only.
- Collect evidence; optional diary for lineage.
- Promote durable truth to lab, then public; breadcrumb infra changes.
- Stop sandboxes you started or used (§5). Submit feedback only for signal (dedup first).
4. Rule-change protocol
propose (local draft, no secrets)
→ sandbox verify (lane-appropriate; stop sandbox when done)
→ evidence receipt
→ promote lab (Explorer published SOT)
→ promote public (manual; no auto-sync)
→ capability breadcrumb if infra-affecting
→ update capability card(s)
MUST NOT silently edit binding rules. Every promoted rule change MUST carry: owner-decision ref (if any), sandbox lane used, evidence pointer, audit/breadcrumb id when available.
Lab vs public: Lab catalog is authenticated write-SOT for AI-visible governance. Public is filled from lab by explicit promote. After every governance publish, verify public context HTTP 200.
Lane sandboxes (verify only)
| Work | Sandbox | MUST NOT |
|---|---|---|
| Explorer app / content pipeline | CT126 | Mutate lab Explorer prod for exploratory work |
| Cortex | CT124 | Auto-load legacy memory; treat sandbox as prod |
| Beacon experiments | CT123 | Treat as prod edge |
| UAI Mail | VPS loopback / agent-first path | Restart Mailu; public MX without owner |
| Mac sketches | Files-only trees | Host any product runtime |
Denied Explorer surfaces remain: admin APIs, raw filesystem, uploads, SQLite, env files, ssh dirs, raw-survey-zone, arbitrary path search through Explorer.
5. Sandboxes = KEEP (owner rule — teeth)
Panel/director “retire sandboxes” is WRONG. Owner rule overrides.
| Rule | Text |
|---|---|
| KEEP | Sandboxes (CT123, CT124, CT126, and peer lab sandboxes) are permanent lab assets. They are not wipe-retire targets by default. |
| MUST stop | When finished working on a sandbox, agents MUST stop the container/VM (free RAM). |
| MUST NOT destroy | Agents MUST NOT destroy, purge, or delete sandboxes unless a separate owner-signed destroy stage explicitly lists that VMID. |
| MUST NOT idle-run | Agents MUST NOT leave sandboxes running after work. Idle-running is a failure. |
| Stage 3 default | Staged wipe Stage 3 MUST NOT list sandboxes for destroy by default. Candidate-IN language that treats sandboxes as disposable retire targets is superseded. |
Correct lifecycle: start/use for lane work → verify → evidence → stop → leave intact for next agent.
Wrong lifecycle: destroy when done · leave running overnight · treat “sandbox” as “free to wipe.”
6. Infrastructure matrix
| Surface | Role | Agent rule |
|---|---|---|
| VPS | Production weight: Beacon + Cortex (P0). Mesh live OK. Mail agent-first rebuild. Public Explorer UI. | MUST NOT treat VPS Cadence as home (drift). |
| NUC | Cadence canonical lab controller | Post-wipe Cadence lives here; preserve jobs DB with NUC Cadence. |
| Lab Proxmox | Explorer lab SOT host (currently CT121), sandboxes CT123/124/126 (KEEP), other owner-listed CTs | Sandboxes: stop-when-done, never destroy by default. CT121: no exploratory mutation; no wipe without dedicated plan. |
| Mac | Docs, Obsidian, off-host archives, agent workstations | mac_hosting=never — MUST NOT host product runtimes (including Cadence). MUST NOT hoard local copies of catalog, runtime DBs, or product data (local_data_hoarding=never). |
| Forge / CT103 | Runtime-retired engineering archive host | MUST NOT revive. Destroy only after off-host vzdump proof + owner Stage 1. |
| Sandboxes | Dev/verify only | KEEP + stop when done (§5). Never promote sandbox as production without evidence. |
Standing policies (owner keys)
| Key | Value |
|---|---|
mac_hosting |
never |
cadence_runtime_home |
nuc_lab_controller |
cortex_new_start |
fresh |
cortex_legacy_memory |
backup_index_filter_later |
mesh_priority |
defer_cutover_live_ok |
uai_mail_ai_access |
rebuild_agent_surface |
uapi_diffuser_b70 |
delayed_possible_intel_rma |
github_org |
decide_later |
sandbox_posture |
keep_stop_when_done |
local_data_hoarding |
never |
B70 is delayed / possible RMA — not a wipe gate; UAI Diffuser does not depend on B70.
Mesh-next deferred — live Mesh leave-as-is.
Mail agent-first — Mailu stopped/archived; no public MX without owner.
7. Post-wipe order (first → last)
| Step | Work | Priority |
|---|---|---|
| 0 | Access + operator tooling restore | Foundation |
| 1 | GitHub private org/remotes when ready | Foundation |
| 2 | Beacon restore / deploy / test | P0 |
| 3 | Cortex infra as needed + fresh app memory + private, then public when ready | P0 |
| 4 | Explorer | After P0 |
| 5 | Cadence on NUC | After Explorer |
| 6 | UAI Mail agent-first on VPS | After Cadence |
| 7 | Diffuser, Switchboard, Command Center, Thinktank | Secondary |
| 8 | Mesh-next | Only if owner reopens |
MUST NOT reorder without owner. MUST NOT start steps 4–8 before Beacon and Cortex meet P0.
8. Staged wipe — agent MUST NOTs
Staged wipe packet is the operational approval surface. Agents MUST NOT fill owner checkboxes.
| MUST NOT | Why |
|---|---|
| Execute any wipe/destroy without the matching owner-signed stage | Stage 0 incomplete ⇒ NOT GO-READY |
| Treat governance publish alone as wipe authorization | Publish ≠ signoff |
| Destroy CT103 without off-host vzdump proof + Stage 1 | Sole-copy risk |
| Wipe VPS operator CLI trees without carbon-copy or proven excludes | Tooling loss |
| Destroy sandboxes (CT123/124/126 …) as part of “lab cleanup” | Sandboxes are KEEP |
| Wipe CT121 Explorer without a dedicated replace/restore plan | Lab published SOT host |
| Host products on Mac during or after wipe | mac_hosting=never |
| Auto-import CT103 or legacy memory into new Cortex | cortex_new_start=fresh |
| Prioritize mesh-next, public MX, or B70 as wipe blockers | Deferred / side-quest / delayed |
| Invent wipe targets or public git remotes | Owner lists only |
Stage map (reference only — not authorization):
Stage 0 Blockers before any wipe
Stage 1 CT103 destroy on Forge (after archive) — not sandboxes
Stage 2 VPS wipe (excludes / carbon-copy restore)
Stage 3 Lab CT wipes — owner-listed VMIDs only; sandboxes KEEP by default
Stage 4 Recommission — post-wipe order (§7)
9. Capability cards
Before first use of a host, service, or hardware you will mutate: read capability-map. If no card matches → abort and feedback missing-context.
After create/modify/delete of service, route, file, config, container, mesh peer, or DNS record: post a breadcrumb as you work.
Required fields when authoring/correcting cards: host/endpoint, role (canonical|drift|sandbox|archive), lane (VPS|NUC|Mac|mesh), post-wipe order index or n/a, drift status, sandbox verify path, owner-decision ref.
Known map debt (do not invent facts to fill gaps): cortex, mail, NUC-host, Mac-policy cards; Cadence cards must mark NUC canonical / VPS drift. Missing card ⇒ abort on mutate, not “guess.”
10. Feedback and promotion
- Categories:
beneficial,not-working,consider,missing-context,qol,blocked. - Dedup before submit. Reference existing ids.
- Feedback is not a rule. Change rules via catalog create/edit or promotion, then verify context 200.
- MUST NOT include credentials, tokens, private keys, private paths, or unredacted survey material.
11. Security and redaction
- Server-side redaction is mandatory; agents still MUST NOT paste secrets.
- AI output has no authority to approve infrastructure exposure, mark wipe complete, sign owner stages, or mutate production without an owner-approved runbook.
- Explorer is best for: published rules, catalog, capability map, breadcrumbs, feedback aggregation, redacted context packets.
- MUST NOT live only in Explorer: active in-motion plans, long evidence blobs, secrets, unredacted archives.
- MUST NOT mirror Explorer catalog or runtime dumps into Mac/agent workspace as working copies — read via API; write receipts to authorized handoff paths only.
- Public HTML document viewer is redacted reading aid only — agents MUST verify via AI context packets.
13. No local copies / no data hoarding
Explorer is source of truth. Agents MUST NOT duplicate or store local copies of docs, secrets, product data, or ecosystem state on workstation disks when working in the lab.
| Rule | Agent obligation |
|---|---|
| Do not hoard | MUST NOT clone or store duplicate doc trees, databases, or product data on Mac/agent workspace unless explicitly authorized |
| Bootstrap from Explorer | MUST read context via GET /api/ai/context/{slug} — MUST NOT scrape catalog and hoard offline mirrors |
| Runtime data off-Mac | Runtime data lives on designated hosts (VPS, NUC, lab CTs) — MUST NOT treat Mac as runtime data home |
| Mac role | Workstation + owner preserve archives only — mac_hosting=never extends to data hoarding (local_data_hoarding=never) |
| Need persistence? | Use Explorer feedback lane or a designated remote path — MUST NOT create ad-hoc local caches |
Authorized exceptions: wipe handoff receipts, START_HERE entry chain, and owner preserve paths when a runbook explicitly authorizes read/write. Preserve archives are owner-controlled — not agent working mirrors.
Ties to: server-side redaction (§11 — secrets never enter local hoards), sandbox verify-only posture (§4 — Mac sketches are files-only, not data warehouses), Explorer SOT (§12 — catalog is read via API, not cloned).
12. What Explorer is (and is not)
Is: publication and enforcement surface for rules; lab write-SOT; public promote target; human operator console for browsing redacted catalog docs.
Is not: live-host policy oracle; Mac archive browser; wipe authorization; sandbox destroy license.
Host placement for the lab catalog today is CT121 — that is where SOT is hosted, not the definition of ecosystem authority. Ecosystem authority is layers §1 + matrix §6.