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.

Cluster Infrastructure

The following services are available in the cluster. Use them via their operators — do not install standalone instances.

Layer	Technology	Policy
Database	CNPG (CloudNativePG)	All PostgreSQL via CNPG Cluster CRDs. No manual Postgres installs, no SQLite in production.
Cache / Pub-sub	DragonflyDB Operator	Redis-compatible via Dragonfly CRDs. No standalone Redis.
MQTT	EMQX Operator	MQTT broker via EMQX CRDs. For IoT and messaging workloads.
Block storage	TrueNAS CSI	All PVCs backed by TrueNAS SCALE.
File / Object storage	Rook-Ceph	CephFS for shared filesystems, RGW for S3-compatible object storage.
Auth	Authentik	OIDC/SSO for all web apps. No custom auth systems.
Monitoring	Prometheus Stack	Create ServiceMonitors and PrometheusRules for all services. AlertManager for alerting.
MariaDB	MariaDB Operator	Available via MariaDB CRDs if needed. Not currently used by Paperclip orgs.

Infrastructure Deployment

Infrastructure deploys through a two-stage GitOps pipeline:

1. Org infra repo (<org>/infra) — contains the Kubernetes manifests for this org's applications (deployments, services, CNPG clusters, etc.)
2. Platform repo (cpfarhood/kubernetes) — contains Flux Kustomizations that reference each org's infra repo. Flux watches THIS repo, not the org infra repos directly.

When you need an infrastructure change:

1. Commit the manifest change to your org's infra repo (e.g., cartsnitch/infra, groombook/infra)
2. If the change requires a NEW resource that Flux doesn't already reference (new Kustomization, new namespace, new sealed secret), a corresponding change to cpfarhood/kubernetes is also needed — create a Paperclip issue for the board
3. If the change is to an EXISTING resource already tracked by Flux, committing to the org infra repo is sufficient — Flux will pick it up on the next reconciliation cycle

Do NOT assume that committing to the org infra repo is always sufficient. New resources, new namespaces, and new secrets require platform repo changes that only the board can make.

• kubectl is available and agents have the following access:
  • Cluster-wide: read-only (get, list, watch) across all namespaces
  • privilegedescalation namespace: read-write (production — changes MUST go through Flux, not kubectl)
  • privilegedescalation-dev namespace: read-write (development — agents may use kubectl freely for testing, debugging, and iteration)
• Production (privilegedescalation): All changes go through the infra repo and Flux. Do not kubectl apply to production. Flux will revert manual changes.
• Development (privilegedescalation-dev): Agents may kubectl apply, kubectl delete, and use any mutating commands freely. This namespace is for testing and validation before committing to the infra repo.
• Headlamp: Production Headlamp runs in kube-system. Development/testing Headlamp instances go in privilegedescalation-dev. Never deploy test plugins to the production Headlamp in kube-system.
• If you need a production 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.
• When creating a new pull request, include cc @cpfarhood at the bottom of the PR body.

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.