GitOps & DevOps Operational Covenant

This document establishes the binding, high-priority system directive governing all coding, configuration, and deployment operations. It ensures that every intellectual transition is transparently tracked, documented, and fully reversible, enabling humans, AI agents, and future witnesses to review the complete developmental evolution of the Fieldprint and Intellecton platforms.

The Five Core Primitives

1. Git-First Version Control (Volatile Isolation Prohibited)

Zero Untracked Edits: No file in the application workspace (/home/antigravity/fieldprint-portal/, /home/antigravity/intellecton-portal/, etc.) shall be modified or introduced without immediate staging in the local Git directory.
Semantic Commits: All updates must be packaged under high-precision, descriptive commit messages specifying the exact features modified (e.g., feat:, fix:, refactor:, docs:).
Continuous Synchronization: Pushes to the sovereign Gitea remote instance at http://forgejo:3001 must be triggered immediately after local validation, ensuring off-host permanence.

2. Declarative Infrastructure (GitOps)

Code-Driven Deployments: Kubernetes deployments, Traefik ingress routing tables, and database configurations must be declared in YAML manifests under /home/antigravity/master-fieldprint/ rather than via manual terminal commands.
Rollback Capability: The declarative repository state must always remain the single source of truth, enabling one-click cluster restoration (kubectl apply -f ... or ansible-playbook) to any historical commit SHA.
Network & Host Resilience: Host-level configurations (e.g., static IP allocations on Proxmox hypervisors) must be documented in the network topology index and configured statically to prevent volatile DHCP state loss.

3. The Continuous Witness Ledger (Traceability)

Living Milestones: Every active task must compile a detailed task.md TODO register, tracking progress from pending [ ] to active [/] to complete [x].
The Historical Lineage: Major engineering phases and structural layout patches must append directly to a unified walkthrough.md, outlining:
- Key architectural decisions and the technical rationale.
- System diagnostics, log results, and performance telemetry.
- Clickable links to modified source files and operational parameters.
Transparency for Peers: The ledger must be written with maximum academic clarity, ensuring other agents or human researchers can instantly step through our developmental reasoning.

4. Continuous Integration & Verification (CI/CD)

Pre-Deployment Audits: Before any image is tagged, pushed to the Tailscale NodePort registry (k8s-01.tailscale:30500), or rolled out to the Atlanta K3s cluster, it must undergo automated validation:
- Static builds (npm run build) must compile with zero linter errors or prerender exceptions.
- Docker compilations must utilize cache-efficient standalone layering.
Zero-Downtime Rollouts: Deployments inside the cluster must utilize Traefik ingress configurations and rolling updates to enable smooth, zero-downtime transition states and immediate rollback targets in the event of anomalies.

5. Hostname-First Protocol (Semantic Network Referencing)

Mandated Hostname Usage: All system configurations, playbooks, remote Git URL endpoints, and registry targets must utilize semantic hostnames (forgejo, k8s-01.tailscale) instead of raw IP addresses.
Self-Referential Clarity: Hostnames preserve cognitive context and reinforce recursive self-referential patterns. IP usage is restricted to low-level DNS bootstrap files.
Note

Due to containerd insecure-registry validation limits on the host k3s nodes, image pulls inside the cluster deployment manifests use the internal service ClusterIP CIDR mapping (10.43.4.37:5000) mapped to registries.yaml mirrors. All external pushes, git syncs, and system playbooks utilize the semantic k8s-01.tailscale and forgejo hostnames.

Enforcement & Inheritance

Important

This covenant is an absolute binding directive. Any specialized subagent (e.g., research, self, or custom systems) spawned in this workspace is strictly commanded to inherit, read, and enforce these core rules. There are no exceptions.

4.3 KiB Raw Permalink Blame History