assistance-engine/CONTRIBUTING.md

Contributing to Brunix Assistance Engine

This document is the single source of truth for all contribution standards in the Brunix Assistance Engine repository. All contributors — regardless of seniority or role — are expected to read, understand, and comply with these guidelines before opening any Pull Request.

---

Table of Contents

1. Development Workflow (GitFlow)
2. Infrastructure Standards
3. Repository Standards
4. Pull Request Requirements
5. Ingestion Files Policy
6. Environment Variables Policy
7. Changelog Policy
8. Documentation Policy
9. Incident & Blockage Reporting

---

1. Development Workflow (GitFlow)

Branch Strategy

Branch type	Naming convention	Purpose
Feature	*-dev	Active development — volatile, no CI validation
Main	online	Production-ready, fully validated

• Feature branches (*-dev) are volatile environments. No validation tests or infrastructure deployments are performed on these branches.
• Official validation only occurs after a documented Pull Request is merged into online.
• Developer responsibility: Code must be stable and functional against the authorized environment before a PR is opened. Do not use the PR review process as a debugging step.

---

2. Infrastructure Standards

The project provides a validated, shared environment (Devaron Cluster, Vultr) including Ollama, Elasticsearch, and PostgreSQL.

• Authorized environment only. The use of parallel, unauthorized infrastructures — external EC2 instances, ad-hoc local setups, non-replicable environments — is strictly prohibited for official development.
• No siloed environments. Isolated development creates technical debt and incompatibility risks that directly impact delivery timelines.
• All infrastructure access must be established via the documented kubectl port-forward tunnels defined in the README.

---

3. Repository Standards

IDE Agnosticism

The online branch must remain neutral to any individual's development environment. The following must not be committed under any circumstance:

• .devcontainer/
• .vscode/
• Any local IDE or editor configuration files

The .gitignore automates exclusion of these artifacts. Ensure your local environment is fully decoupled from the production-ready source code.

Security & Least Privilege

• Never use root as remoteUser in any shared dev environment configuration.
• All configurations must comply with the Principle of Least Privilege.
• Using root in shared environments introduces unacceptable supply chain risk.

Docker & Build Context

• All executable code must reside in /app within the container.
• The /workspace root directory is deprecated — do not reference it.
• Every PR must verify the Dockerfile context is optimized via .dockerignore.

PRs that violate these architectural standards will be rejected without review.

---

4. Pull Request Requirements

A PR is not ready for review unless all applicable items in the following checklist are satisfied. Reviewers are authorized to close PRs that do not meet these standards and request resubmission.

PR Checklist

Code & Environment

• Tested locally against the authorized Devaron Cluster (no unauthorized infrastructure used)
• No IDE or environment configuration files committed (.vscode, .devcontainer, etc.)
• No root user configurations introduced
• Dockerfile and .dockerignore comply with build context standards

Ingestion Files (see Section 5)

• No ingestion files were added or modified
• New or modified ingestion files are committed to the repository under ingestion/ or data/

Environment Variables (see Section 6)

• No new environment variables were introduced
• New environment variables are documented in the .env reference table in README.md

Changelog (see Section 6)

• No changelog entry required (internal refactor, comment/typo fix, zero behavioral change)
• Changelog updated with correct version bump and date

Documentation (see Section 7)

• No documentation update required (internal change, no impact on setup or API)
• README.md or relevant docs updated to reflect this change

---

5. Ingestion Files Policy

All files used to populate the vector knowledge base — source documents, AVAP manuals, structured data, or ingestion scripts — must be committed to the repository.

Rules

• Ingestion files must reside in a dedicated directory (e.g., ingestion/ or data/) within the repository.
• Any PR that introduces new knowledge base content or modifies existing ingestion pipelines must include the corresponding source files.
• Files containing sensitive content that cannot be committed in plain form must be flagged for discussion before proceeding. Encryption, redaction, or a separate private submodule are all valid solutions — committing to an external or local-only location is not.

Why this matters

The Elasticsearch vector index is only as reliable as the source material that feeds it. Ingestion files that exist only on a local machine or external location cannot be audited, rebuilt, or validated by the team. A knowledge base populated from untracked files is a non-reproducible dependency — and a risk to the entire RAG pipeline.

---

6. Environment Variables Policy

This is a critical requirement. Every environment variable introduced in a PR must be documented before the PR can be merged.

Rules

• Any new variable added to the codebase (.env, docker-compose.yaml, server.py, or any config file) must be declared in the .env reference table in README.md.
• The documentation must include: variable name, purpose, whether it is required or optional, and an example value.
• Variables that contain secrets must use placeholder values (e.g., your-secret-key-here) — never commit real values.

Required format in README.md

| Variable | Required | Description | Example |
|---|---|---|---|
| `LANGFUSE_PUBLIC_KEY` | Yes | Langfuse project public key for tracing | `pk-lf-...` |
| `LANGFUSE_SECRET_KEY` | Yes | Langfuse project secret key | `sk-lf-...` |
| `LANGFUSE_HOST`       | Yes | Langfuse server endpoint | `http://45.77.119.180` |
| `NEW_VARIABLE`        | Yes | Description of what it does | `example-value` |

Why this matters

An undocumented environment variable silently breaks the setup for every other developer on the team. It also makes the service non-reproducible, which is a direct violation of the infrastructure standards in Section 2. There are no exceptions to this policy.

---

7. Changelog Policy

The changelog file tracks all notable changes and follows Semantic Versioning.

When a changelog entry IS required

Change type	Label to use
New feature or capability	Added
Change to existing behavior, API, or interface	Changed
Bug fix	Fixed
Security patch or security-related change	Security
Breaking change or deprecation	Deprecated / Removed

When a changelog entry is NOT required

• Typo or comment fixes only
• Internal refactors with zero behavioral or interface change
• Tooling/CI updates with no user-visible impact

If in doubt, add an entry.

Format

New entries go at the top of the file, above the previous version:

## [X.Y.Z] - YYYY-MM-DD

### Added
- LABEL: Description of the new feature or capability.

### Changed
- LABEL: Description of what changed and the rationale.

### Fixed
- LABEL: Description of the bug resolved.

Use uppercase short labels for scanability: API:, DOCKER:, INFRA:, SECURITY:, ENV:, CONFIG:.

---

8. Documentation Policy

When documentation MUST be updated

Update README.md (or the relevant doc file) if the PR includes any of the following:

• Changes to project structure (new files, directories, removed components)
• Changes to setup, installation, or environment configuration
• New or modified API endpoints or Protobuf definitions (brunix.proto)
• New, modified, or removed environment variables
• Changes to infrastructure tunnels or Kubernetes service names
• New dependencies or updated dependency versions
• Changes to security, access, or repository standards

When documentation is NOT required

• Internal implementation changes with no impact on setup, usage, or API
• Fixes that do not alter any documented behavior

PRs that change user-facing behavior or setup without updating documentation will be rejected.

---

9. Incident & Blockage Reporting

If you encounter a technical blockage (connection timeouts, service downtime, tunnel failures):

1. Immediate notification — Report via the designated Slack channel at the moment of detection. Do not wait until end of day.
2. GitHub Issue must include:
   • The exact command executed
   • Full terminal output (complete error logs)
   • Current status of all kubectl tunnels
3. Resolution — If the error is not reproducible by the CTO/DevOps team, a 5-minute live debugging session will be scheduled to identify local network or configuration issues.

---

These standards exist to protect the integrity of the Brunix Assistance Engine and to ensure every member of the team can work confidently and efficiently. They are not bureaucratic overhead — they are the foundation of a reliable, scalable engineering practice.

— Rafael Ruiz, CTO, AVAP Technology