org/POLICIES.md

Privileged Escalation — Shared Policies

All agents in this org must follow these policies.

Environment Variables

PAPERCLIP_API_KEY, PAPERCLIP_API_URL, PAPERCLIP_RUN_ID, PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID are pre-injected into your process environment. Do NOT base64-decode, JWT-parse, or manually verify tokens — just use them directly in commands. If PAPERCLIP_API_URL appears empty in a shell command, use http://localhost:3100 as the API base URL.

Infrastructure

• Container images: Push to ghcr.io only. We do not use Docker Hub, do not mirror public images, and do not maintain any other registry.
• Dependency updates: Managed by Mend Renovate. We do not use Dependabot — never enable it, never create .github/dependabot.yml, never reference it in workflows or docs.
• Plugin installation: ArtifactHub only via Headlamp's native plugin installer. No Helm-based plugin installation, no custom install scripts.

Versioning

All releases use SemVer (semantic versioning). ArtifactHub requires SemVer for Headlamp plugin packages. Do not use CalVer.

Infrastructure Deployment

All infrastructure changes deploy via Flux GitOps. Flux reconciles the org's infra repo to the cluster automatically.

• The only way to change Kubernetes resources is through the infra repo. Commit manifests, push, and Flux deploys. There is no other path.
• kubectl is read-only. You may use kubectl get, kubectl describe, kubectl logs, etc. for troubleshooting and verification. You may NEVER use kubectl apply, kubectl delete, kubectl edit, kubectl patch, kubectl create, or any other mutating command. Flux will revert any manual changes.
• If you need an infrastructure change, create a PR against the infra repo (or create a Paperclip issue for the agent who owns infra).

Git Workflow

• All changes go through feature branches and PRs. Never push directly to main.
• Branch protection: CEOs must enforce the PR workflow via GitHub branch protection rules wherever possible — require PR reviews, require status checks, restrict who can merge. Policy should be enforced by GitHub, not just by agent prompts.
• Do not approve or merge PRs on the privilegedescalation/agents repo — only the board may approve changes to agent configurations and prompts.

PR Workflow

All code changes follow this lifecycle:

1. Engineer opens a PR from a feature branch (never push directly to main)
2. QA (Regina) approves — verifies tests, coverage, regressions, edge cases
3. CTO (Nancy) approves — verifies architecture alignment, code quality, security
4. CEO (Countess) merges — only after both QA and CTO have approved and CI passes

A PR is not ready to merge until it has both QA and CTO approval. No agent merges their own PRs. No agent merges without dual approval.

Issue Tracking

• GitHub issues are the primary tracker. All bugs, features, and work items are tracked as GitHub issues in the relevant repo. Paperclip issues are secondary — use them to trigger and coordinate agents (assignments, status handoffs, heartbeat wakes), not as the primary record of work.
• GitHub issues stay open until deployed and validated. A GitHub issue is not done when a PR is merged. It is done when the change is deployed to production and validated as working. Merging is a step in the process, not the finish line.

Task Assignment

To hand off work to another agent, create a Paperclip issue with assigneeAgentId set:

curl -sf -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -d '{"title": "...", "description": "...", "status": "todo", "assigneeAgentId": "<target-agent-id>", "parentId": "<parent-issue-id-if-subtask>"}'

Always include:

• A clear title and description so the assignee understands the work without asking questions
• assigneeAgentId — the target agent's ID (find IDs in each agent's CONFIG.md)
• parentId if this is a subtask of an existing issue
• A comment on the parent issue noting the delegation

To reassign an existing issue:

curl -sf -X PATCH "$PAPERCLIP_API_URL/api/issues/{issueId}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -d '{"assigneeAgentId": "<target-agent-id>", "comment": "Reassigning because..."}'

Never leave work unassigned. If you cannot do it yourself, assign it to the right agent with context.

CI/CD Workflow Access

Only Hugh Hackman has write access to .github/workflows/ files. All other agents must delegate CI/CD workflow changes to him.