From 2fc48d96370c14230714f309165e0b3aee204f55 Mon Sep 17 00:00:00 2001
From: James <james@jongsma.me>
Date: Wed, 8 Apr 2026 14:34:43 -0400
Subject: [PATCH] Add agent-authored PR workflow to Part 10

- Agent PR workflow with full context requirements
- PR template for agents with security checklist
- Session ID tracking for audit trail
- Human review requirements for security-critical changes
- Future state: limited auto-merge authority
---
 CLAVITOR-PRINCIPLES.md | 109 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)

diff --git a/CLAVITOR-PRINCIPLES.md b/CLAVITOR-PRINCIPLES.md
index 865b78a..c8bba4a 100644
--- a/CLAVITOR-PRINCIPLES.md
+++ b/CLAVITOR-PRINCIPLES.md
@@ -1279,6 +1279,115 @@ Alternative: [safer option]. Proceed?"
 When we add contributor access beyond core team, signed commits (SSH or GPG)
 will be required. All commits must be verifiable.
 
+### Agent-authored PRs (AI-as-contributor)
+
+Since agents (AI assistants) do much of the implementation work, **agents
+should author their own PRs** with full context. This creates an auditable
+trail of AI decision-making.
+
+**Agent PR workflow:**
+
+```bash
+# Agent does the work
+1. git checkout -b agent/rate-limit-defense-20250408
+2. [make changes per CLAVITOR-PRINCIPLES.md]
+3. git commit -m "api: add per-agent rate limiting and lockdown
+
+Implements Threat A defense per CLAVITOR-PRINCIPLES.md Part 2.
+- Rate limit: 3/min, 10/hour distinct entries
+- Two-strike lockdown within 2h window
+- Locked state persisted in encrypted agent record
+
+Author: Claude (agent session 20250408-001)"
+4. git push -u origin agent/rate-limit-defense-20250408
+5. gh pr create --title "Agent: Threat A rate limiting" \
+   --body "$(cat <<'EOF'
+## Summary
+Implements harvester defense per Cardinal Rule #4.
+
+## Changes
+- `lib/types.go`: Add RateLimit, RateLimitHour, Locked fields to AgentData
+- `api/middleware.go`: Per-agent rate limiting in L1Middleware
+- `api/handlers.go`: agentReadEntry call for credential reads
+
+## Security Review Checklist
+- [x] Rate limits default to safe values (3/min, 10/hr)
+- [x] No L2/L3 material on server (verified via Part 4 checks)
+- [x] Audit logging on all state changes
+- [x] IP whitelist enforcement unchanged
+
+## Test Plan
+- Create agent with default limits
+- Trigger rate limit → expect 429
+- Trigger second strike → expect 423 Locked
+- Verify lock persists after vault restart
+
+## Documentation
+- CLAVITOR-PRINCIPLES.md Part 7 updated with unlock procedure
+
+## Risks
+- False positive lock: owner can PRF-unlock via admin endpoint
+- First-contact IP race: accepted risk per existing comment
+EOF
+)"
+```
+
+**PR template for agents:**
+
+Create `.github/PULL_REQUEST_TEMPLATE/agent_pr_template.md`:
+
+```markdown
+## Agent Session
+- Session ID: <!-- agent fills -->
+- Principles reviewed: CLAVITOR-PRINCIPLES.md v<!-- version -->
+- Daily checks: <!-- date agent ran Part 4 -->
+
+## Summary
+<!-- One paragraph: what and why -->
+
+## Changes
+<!-- Bullet list of files changed and key logic -->
+
+## Security Review Checklist
+- [ ] No server-side L2/L3 handling (A1-A3)
+- [ ] Security failures are LOUD (Cardinal Rule #1)
+- [ ] No key material in logs (A6)
+- [ ] Error handling has unique codes (Part 1)
+- [ ] DRY violations checked (Section E)
+- [ ] Test coverage for new logic
+
+## Verification
+<!-- How you tested, or why testing is deferred -->
+
+## Risks & Mitigations
+<!-- What could go wrong, how it's handled -->
+
+## Principle References
+<!-- Which parts of CLAVITOR-PRINCIPLES.md this implements or modifies -->
+```
+
+**Human review points:**
+
+Even agent-authored PRs require human approval before merge:
+1. Security-critical changes → Johan must approve
+2. Schema/data model changes → Review for migration impact
+3. New principles added → Ensure they follow Part 5 format
+4. Violations noted → Confirm documented in Part 6 style
+
+**Agent merge authority:**
+
+Currently: **No auto-merge.** All PRs require human approval.
+Future state: Agents may merge their own PRs for:
+- Documentation fixes
+- Test additions
+- Trivial refactors (no logic change)
+- Daily drift fixes (Part 4 violations)
+
+With safety rules:
+- Never merge to `main` directly
+- Always through PR with CI passing
+- No merge if PR contains "SECURITY" or "veto" in review comments
+
 ---
 
 *Foundation First. No mediocrity. Ever.*