Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<branch>`).

## 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.
9 changes: 9 additions & 0 deletions GEMINI.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
107 changes: 107 additions & 0 deletions docs/agent-staff-governance.md
Original file line number Diff line number Diff line change
@@ -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 |
Loading