From edccd81a381d367a2ee98c2e8b5e5eb338fcf21f Mon Sep 17 00:00:00 2001 From: groupthinking <154503486+groupthinking@users.noreply.github.com> Date: Fri, 13 Nov 2026 09:55:47 +0000 Subject: [PATCH] docs: adopt agent staff governance and single approval gate Closes #2671 --- AGENTS.md | 9 +++ CHANGELOG.md | 10 +++ CLAUDE.md | 9 +++ GEMINI.md | 9 +++ docs/agent-staff-governance.md | 107 +++++++++++++++++++++++++++++++++ 5 files changed, 144 insertions(+) create mode 100644 docs/agent-staff-governance.md diff --git a/AGENTS.md b/AGENTS.md index f2ffa60bd..3d67fcd03 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,3 +105,12 @@ PYTHONPATH=src python3 scripts/nightly_audit_agent.py --dry-run ## Security dependency maintenance For an advisory-driven dependency update, follow [docs/security-dependency-maintenance.md](docs/security-dependency-maintenance.md). Reuse the canonical issue/PR, preserve direct versus transitive dependencies, and include the Security dependency evidence block. Before an authorized merge, re-fetch the exact head, applicable checks, reviews, unresolved threads, and mergeability; use expected-head protection and record the resulting merge commit. A recipe or green historical run is not current verification. This procedure grants no deployment or spending authority. + +## Agent staff governance + +Full spec: [docs/agent-staff-governance.md](docs/agent-staff-governance.md). + +- **Five rules:** (1) no external state change without a standing policy or task authorization; (2) one human approval gate; (3) all work committed to a tracked GitHub branch; (4) a changelog entry linked to the issue, PR, or Video Pack hash; (5) every fix leaves an SOP and a regression test or check. +- **The one gate (Hayden):** production deploys, live database changes, billing, entitlements and spend, and credentials or access settings. CI-green merges to `main` that touch none of these fall under the standing merge policy (POL-001) and MERGE_POLICY.md. +- **Policy loop:** spot the inconsistency, propose a rule plus its check, Hayden approves it once, then codify it and enforce it automatically. +- **Hiring brief:** every agent role states what it owns, how it thinks, its definition of done, and what it never touches. It states its execution limits before taking work and never claims access it lacks. diff --git a/CHANGELOG.md b/CHANGELOG.md index 03f2628eb..a551153a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,16 @@ versioning aims for [SemVer](https://semver.org/). ## [Unreleased] +### 2026-11-13: Agent staff governance (docs) + +#### Added + +- `docs/agent-staff-governance.md`: five rules, a single human approval gate + (production deploys, live DB, billing/spend, credentials/access), a standing + CI-green merge policy (POL-001), the inconsistency-to-policy loop, and the + agent hiring brief. +- Summary section in `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` pointing to it. + ### 2026-05-22 — UVAI Phase 1: SEO, a11y, static assets Baseline pulse identified the following gaps between repo `main` and the live diff --git a/CLAUDE.md b/CLAUDE.md index 1076e5ccd..4049d0339 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -154,3 +154,12 @@ Do not add `try/except TypeError` fallbacks around these parameters — if the S - **History was rewritten**: `main` has been force-pushed (a secret-purge of committed credentials). Older branches are therefore *orphaned* — they share little real ancestry with current `main`. Consequence: `git diff main...branch` (three-dot) and `git merge-tree` are **unreliable** for those branches (a three-dot diff can read "0 files" for a branch that diverges by thousands; merge-tree reports "clean" because unrelated trees don't textually conflict). When auditing branches, trust **PR state + staleness** (age, commits-behind), not raw diffs. - **Branch audits**: use the `branch-cleanup` skill (`.claude/skills/branch-cleanup/`) — it runs the 6-gate fail-test harness (`scripts/maintenance/branch-fail-test.sh`) and emits a decision matrix. Never delete branches without archive-tagging first (`git tag archive/`). + +## Agent staff governance + +Full spec: [docs/agent-staff-governance.md](docs/agent-staff-governance.md). + +- **Five rules:** (1) no external state change without a standing policy or task authorization; (2) one human approval gate; (3) all work committed to a tracked GitHub branch; (4) a changelog entry linked to the issue, PR, or Video Pack hash; (5) every fix leaves an SOP and a regression test or check. +- **The one gate (Hayden):** production deploys, live database changes, billing, entitlements and spend, and credentials or access settings. CI-green merges to `main` that touch none of these fall under the standing merge policy (POL-001) and MERGE_POLICY.md. +- **Policy loop:** spot the inconsistency, propose a rule plus its check, Hayden approves it once, then codify it and enforce it automatically. +- **Hiring brief:** every agent role states what it owns, how it thinks, its definition of done, and what it never touches. It states its execution limits before taking work and never claims access it lacks. diff --git a/GEMINI.md b/GEMINI.md index 96c19a5bb..245594564 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -128,3 +128,12 @@ npm --workspace=apps/web run type-check - Backend-dependent actions use `BACKEND_URL` plus the backend's own configured credentials. Missing configuration is not evidence of a successful action. - Auth, billing, and CLI/MCP credentials belong to their existing integrations. Never print secrets or commit environment files. - Inspect `.gemini/settings.json` and run `/mcp` before assuming an optional tooling service is connected. See [README.md](README.md) for the current development path. + +## Agent staff governance + +Full spec: [docs/agent-staff-governance.md](docs/agent-staff-governance.md). + +- **Five rules:** (1) no external state change without a standing policy or task authorization; (2) one human approval gate; (3) all work committed to a tracked GitHub branch; (4) a changelog entry linked to the issue, PR, or Video Pack hash; (5) every fix leaves an SOP and a regression test or check. +- **The one gate (Hayden):** production deploys, live database changes, billing, entitlements and spend, and credentials or access settings. CI-green merges to `main` that touch none of these fall under the standing merge policy (POL-001) and MERGE_POLICY.md. +- **Policy loop:** spot the inconsistency, propose a rule plus its check, Hayden approves it once, then codify it and enforce it automatically. +- **Hiring brief:** every agent role states what it owns, how it thinks, its definition of done, and what it never touches. It states its execution limits before taking work and never claims access it lacks. diff --git a/docs/agent-staff-governance.md b/docs/agent-staff-governance.md new file mode 100644 index 000000000..6c0e918d7 --- /dev/null +++ b/docs/agent-staff-governance.md @@ -0,0 +1,107 @@ +--- +policy_version: v1 +status: proposed +owner: Hayden Garvey +adopted: pending merge +--- + +# Agent Staff Governance + +Five rules, one approval gate, and a policy loop for every agent that works in +this repo (Claude, Gemini, Grok, Jules, Copilot, Hark, and any agent declared in +`config/agent_network.json`). Adapted from "Hire Agents Like Staff" and "From +Inconsistency to Policy". This doc complements [MERGE_POLICY.md](../MERGE_POLICY.md) +and does not replace it. Where they overlap, MERGE_POLICY.md governs merge +mechanics and this doc governs authority. + +## Why the gate is narrow + +A human yes on every change to `main` was tried and it stalled the work. In one +24-hour window an always-on agent woke 47 times and acted on nothing, because +every next step was waiting on an approval. MERGE_POLICY.md v2 already +documents the same failure for unsatisfiable gates: work piles up in draft, and +people learn to merge around the gate. So the human gate covers the +irreversible and the expensive. Everything else runs on policies the owner +approves once. + +## 1. The five rules + +1. **No action without permission.** Agents may analyze, plan, draft, and work + in branches or worktrees freely. A state-changing action outside the repo + (a send, a post, a purchase, a deploy, an external API write) needs either an + approved standing policy that covers it or explicit task authorization. +2. **One approval gate for production.** Hayden's explicit approval is + required for: + - deploys or promotions to production (live `uvai.io` / Vercel production), + - live database changes (migrations, data writes, RLS changes on any + production Supabase project), + - billing, entitlements, pricing, or any spend, + - credentials, secrets, and access settings (repo settings, branch + protection, tokens). + + Merges to `main` that touch none of the above are covered by the standing + merge policy below. They still go through the MERGE_POLICY.md gates and must + pass Staging/Judge verification. +3. **All work backed up to GitHub.** Every code change, skill, harness, and + config change is committed and pushed to a tracked branch. Nothing lives only + in an ephemeral sandbox. +4. **A changelog for everything.** Every merged PR and every state transition + records why it happened and links the issue, PR, or Video Pack hash that + triggered it (PR body plus a `CHANGELOG.md` entry for user-visible changes). +5. **Everything gets documented.** Every fix or incident leaves a short SOP + (what happened, how it was caught, how to prevent it, how to handle it next + time) and a regression test or CI check, so the fix compounds. + +## 2. Standing merge policy (approved once) + +An agent may merge a PR to `main` without a per-PR approval when all of these +hold: + +- Every required check is green on the exact head SHA, re-read just before + merge (a green historical run is not current verification). +- No unresolved review threads, and no changes requested. +- The PR binds exactly one issue (`Closes #N`) and follows MERGE_POLICY.md. +- The diff touches nothing behind the approval gate (section 1, rule 2), and no + hold applies (for example a hold that waits on another PR leaving draft). +- No force-push, no history rewrite, and merge with expected-head protection. + +After merging, the agent reports what merged and the merge commit. + +## 3. From inconsistency to policy + +1. **Spot the inconsistency.** Drift, a silent dependency or model update, a + spec mismatch, or a repeated manual approval. +2. **Propose a policy.** A deterministic rule plus the test or CI check that + enforces it. Fix the class of problem, not just the one instance. +3. **Hayden approves it once.** He signs off on the policy, not on each + individual patch. +4. **Make it official.** Write the rule into this doc or AGENTS.md, add the + CI or eval gate, and enforce it automatically from then on. + +Approved policies are listed in the Policy register below, newest first. + +## 4. Hiring brief for every agent role + +Every agent role (Design, Code, Agent, Maintainer, Owner, Operator, and +Staging/Judge) is defined by a three-part brief, and must state its limits +before it takes work: + +- **Owns:** the whole surface it is responsible for, end to end. +- **Thinks:** verifies from first principles, prefers structured evidence to + narrative, fails closed on unimplemented routes, and never fabricates a + success state. This is consistent with Zero-Sim and G.A.T.E. in AGENTS.md. +- **Accountable for:** + - *Done* means it builds and type-checks (`tsc --noEmit`, `ruff`, `pytest` as + applicable), passes Staging/Judge, matches provenance where a Video Pack + applies, and ships with a changelog entry and an SOP. + - *Never touch without asking:* anything behind the approval gate. + +**Limit disclosure:** at the start of a task, an agent says what it can execute +directly and what needs staging or a human handoff. It never claims write or +deploy access it does not have. + +## Policy register + +| ID | Policy | Approved | +| --- | --- | --- | +| POL-001 | Standing merge policy (section 2) | On merge of this doc |