CONSTITUTION.json

{
  "version": "1.4.0",
  "project_name": "HelixAgent",
  "summary": "Constitution with 31 rules (31 mandatory) across categories: Quality: 2, Safety: 1, Security: 1, Performance: 2, Containerization: 5, Configuration: 2, Testing: 5, Documentation: 2, Principles: 2, Stability: 1, Observability: 1, GitOps: 2, CI/CD: 1, Architecture: 1, Networking: 1, Resource Management: 1, Concurrency: 1",
  "created_at": "2026-02-10T00:18:38.71286699+03:00",
  "updated_at": "2026-04-21T00:00:00+03:00",
  "rules": [
    {
      "id": "CONST-001",
      "category": "Architecture",
      "title": "Comprehensive Decoupling",
      "description": "Identify all parts and functionalities that can be extracted as separate modules (libraries) and reused in various projects. Perform additional work to make each module fully decoupled and independent. Each module must be a separate project with its own CLAUDE.md, AGENTS.md, README.md, docs/, tests, and challenges.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-002",
      "category": "Testing",
      "title": "100% Test Coverage",
      "description": "Every component MUST have 100% test coverage across ALL test types: unit, integration, E2E, security, stress, chaos, automation, and benchmark tests. No false positives. Use real data and live services (mocks only in unit tests).",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-003",
      "category": "Testing",
      "title": "Comprehensive Challenges",
      "description": "Every component MUST have Challenge scripts validating real-life use cases. No false success - validate actual behavior, not return codes.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-004",
      "category": "Documentation",
      "title": "Complete Documentation",
      "description": "Every module and feature MUST have complete documentation: README.md, CLAUDE.md, AGENTS.md, user guides, step-by-step manuals, video courses, diagrams, SQL definitions, and website content. No component can remain undocumented.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-005",
      "category": "Quality",
      "title": "No Broken Components",
      "description": "No module, application, library, or test can remain broken, disabled, or incomplete. Everything must be fully functional and operational.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-006",
      "category": "Quality",
      "title": "No Dead Code",
      "description": "Identify and remove all 'dead code' - features or functionalities left unconnected with the system. Perform comprehensive research and cleanup.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-007",
      "category": "Safety",
      "title": "Memory Safety",
      "description": "Perform comprehensive research for memory leaks, deadlocks, and race conditions. Apply safety fixes and improvements to prevent these issues.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-008",
      "category": "Security",
      "title": "Security Scanning",
      "description": "Execute Snyk and SonarQube scanning. Analyze findings in depth and resolve everything. Ensure scanning infrastructure is accessible via containerization (Docker/Podman).",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-009",
      "category": "Performance",
      "title": "Monitoring and Metrics",
      "description": "Create tests that run and perform monitoring and metrics collection. Use collected data for proper optimizations.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-010",
      "category": "Performance",
      "title": "Lazy Loading and Non-Blocking",
      "description": "Implement lazy loading and lazy initialization wherever possible. Introduce semaphore mechanisms and non-blocking mechanisms to ensure flawless responsiveness.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-011",
      "category": "Principles",
      "title": "Software Principles",
      "description": "Apply all software principles: KISS, DRY, SOLID, YAGNI, etc. Ensure code is clean, maintainable, and follows best practices.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-012",
      "category": "Principles",
      "title": "Design Patterns",
      "description": "Use appropriate design patterns: Proxy, Facade, Factory, Abstract Factory, Observer, Mediator, Strategy, etc. Apply patterns where they add value.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-013",
      "category": "Stability",
      "title": "Rock-Solid Changes",
      "description": "All changes must be safe, non-error-prone, and MUST NOT BREAK any existing working functionality. Ensure backward compatibility unless explicitly breaking.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-014",
      "category": "Testing",
      "title": "Stress and Integration Tests",
      "description": "Introduce comprehensive stress and integration tests validating that the system is responsive and not possible to overload or break.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-015",
      "category": "Containerization",
      "title": "Full Containerization",
      "description": "All services MUST run in containers (Docker/Podman/K8s). Support local default execution AND remote configuration. Services must auto-boot before HelixAgent is ready.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-015a",
      "category": "Containerization",
      "title": "Mandatory Container Orchestration Flow",
      "description": "The ONLY acceptable container orchestration flow: (1) HelixAgent boots and initializes Containers module adapter, (2) Adapter reads containers/.env file (NOT project root .env), (3) Based on CONTAINERS_REMOTE_ENABLED: true=ALL containers to remote hosts via CONTAINERS_REMOTE_HOST_* vars, false/missing=ALL containers locally, (4) Health checks against configured endpoints, (5) Required services failing health check cause boot failure. Rules: NO manual container starts, NO mixed mode, tests use tests/precondition/containers_boot_test.go, challenges verify container placement. Key files: containers/.env, internal/config/config.go:isContainersRemoteEnabled(), internal/services/boot_manager.go, tests/precondition/containers_boot_test.go.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-21T15:45:00.000000000+03:00",
      "updated_at": "2026-02-21T15:45:00.000000000+03:00"
    },
    {
      "id": "CONST-016",
      "category": "Configuration",
      "title": "Unified Configuration",
      "description": "CLI agent config export uses only HelixAgent + LLMsVerifier's unified generator. No third-party scripts.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-017",
      "category": "Observability",
      "title": "Health and Monitoring",
      "description": "Every service MUST expose health endpoints. Circuit breakers for all external dependencies. Prometheus/OpenTelemetry integration.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-018",
      "category": "GitOps",
      "title": "GitSpec Compliance",
      "description": "Follow GitSpec constitution and all constraints from AGENTS.md and CLAUDE.md.",
      "mandatory": true,
      "priority": 2,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-018a",
      "category": "GitOps",
      "title": "SSH Only for Git Operations",
      "description": "MANDATORY: NEVER use HTTPS for any Git service operations. All cloning, fetching, pushing, and submodule operations MUST use SSH URLs (git@github.com:org/repo.git). HTTPS is STRICTLY FORBIDDEN even for public repositories. SSH keys are already configured on all Git services (GitHub, GitLab, etc.).",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-21T16:30:00.000000000+03:00",
      "updated_at": "2026-02-21T16:30:00.000000000+03:00"
    },
    {
      "id": "CONST-019",
      "category": "CI/CD",
      "title": "Manual CI/CD Only",
      "description": "NO GitHub Actions, GitLab CI/CD, or any automated pipeline may exist in this repository! NO Git hooks (pre-commit, pre-push, post-commit, etc.) may be installed or configured. All builds, tests, and quality checks must be executed manually only via Makefile targets. This rule is permanent and non-negotiable.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-020",
      "category": "Documentation",
      "title": "Documentation Synchronization",
      "description": "Anything added to Constitution MUST be present in AGENTS.md and CLAUDE.md, and vice versa. Keep all three synchronized.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-10T00:18:38.712867251+03:00",
      "updated_at": "2026-02-10T00:18:38.712867251+03:00"
    },
    {
      "id": "CONST-021",
      "category": "Containerization",
      "title": "Container-Based Builds",
      "description": "ALL release builds MUST be performed inside Docker/Podman containers for reproducibility. Use `make release` / `make release-all`. Version info injected via `-ldflags -X`. No release binaries should be built directly on the host unless container build is unavailable.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-17T12:00:00.000000000+03:00",
      "updated_at": "2026-02-17T12:00:00.000000000+03:00"
    },
    {
      "id": "CONST-022",
      "category": "Testing",
      "title": "Infrastructure Before Tests",
      "description": "ALL infrastructure containers (PostgreSQL, Redis, Mock LLM) MUST be running before executing tests or challenges. Use `make test-infra-start` or `make test-infra-direct-start` (Podman fallback with `--userns=host`). Tests and challenges that require infrastructure WILL FAIL without running containers.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-02-17T12:00:00.000000000+03:00",
      "updated_at": "2026-02-17T12:00:00.000000000+03:00"
    },
    {
      "id": "CONST-015b",
      "category": "Containerization",
      "title": "Mandatory Container Rebuild",
      "description": "All running containers on local host or remote distributed machines MUST be rebuilt and redeployed if code was changed affecting any of them. After any code changes to services, handlers, MCPs, formatters, or any containerized component: (1) Rebuild affected images with `make docker-build` or `make container-build`, (2) Restart containers with `make docker-run` or `make container-start`, (3) If using remote distribution, re-run distribution with `CONTAINERS_REMOTE_ENABLED=true`. Failure to rebuild containers after code changes will result in outdated code running in production.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-03-16T00:00:00.000000000+03:00",
      "updated_at": "2026-03-16T00:00:00.000000000+03:00"
    },
    {
      "id": "CONST-023",
      "category": "Networking",
      "title": "HTTP/3 (QUIC) with Brotli Compression",
      "description": "ALL HTTP communication MUST use HTTP/3 (QUIC) as primary transport with Brotli compression. HTTP/2 only as fallback when HTTP/3 is unavailable. Compression priority: Brotli (primary) then gzip (fallback). All HTTP clients and servers MUST prefer HTTP/3. Use `quic-go/quic-go` for transport and `andybalholm/brotli` for compression.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-03-16T00:00:00.000000000+03:00",
      "updated_at": "2026-03-16T00:00:00.000000000+03:00"
    },
    {
      "id": "CONST-024",
      "category": "Resource Management",
      "title": "Test and Challenge Resource Limits",
      "description": "ALL test and challenge execution MUST be strictly limited to 30-40% of host system resources. Use GOMAXPROCS=2, nice -n 19, ionice -c 3, and -p 1 for go test. Container limits required. Host machine runs mission-critical processes; exceeding limits has caused system crashes and forced resets.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-03-16T00:00:00.000000000+03:00",
      "updated_at": "2026-03-16T00:00:00.000000000+03:00"
    },
    {
      "id": "CONST-016a",
      "category": "Configuration",
      "title": "Non-Interactive Execution",
      "description": "ALL commands MUST be fully non-interactive and automatable via command pipelines. NEVER prompt for passwords, passphrases, or any user input interactively. SSH connections MUST use key-based authentication with SSH agent (ssh-add) or password provided via environment variables/sshpass. Container distribution to remote hosts MUST be fully automated through the Containers module's SSH executor with pre-configured credentials. All secrets (API keys, passwords, SSH keys) MUST be provided via environment variables or .env files, never via interactive prompts.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-03-16T00:00:00.000000000+03:00",
      "updated_at": "2026-03-16T00:00:00.000000000+03:00"
    },
    {
      "id": "CONST-029",
      "category": "Concurrency",
      "title": "Concurrent-Safe Containers",
      "description": "Any struct field that is a mutable collection (map, slice, channel-map) and is accessed concurrently MUST use safe.Store[K,V] or safe.Slice[T] from digital.vasic.concurrency/pkg/safe. Bare sync.Mutex + map / sync.Mutex + slice combinations in shared state are prohibited for new code. Primitives never expose the internal collection (no Raw/Map/Slice/Internal methods). Atomic read-modify-write goes through Update/UpdateAt callbacks. Never mutate inside Range (deadlock) — snapshot, iterate, apply. Discipline and migration table in docs/development/concurrency-playbook.md. Enforced via scripts/concurrency-audit.sh under make ci-validate-all.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-04-19T16:16:18",
      "updated_at": "2026-04-19T16:16:18"
    },
    {
      "id": "CONST-030",
      "category": "Testing",
      "title": "Real Infrastructure for All Non-Unit Tests",
      "description": "Mocks, stubs, fakes, placeholders, and hardcoded data MAY be used ONLY in unit tests (files ending _test.go run under `go test -short`). ALL other test types — integration, E2E, functional, security, stress, chaos, challenge, benchmark, HelixQA, and any runtime verification — MUST execute against the REAL running HelixAgent system with REAL containers, REAL databases, REAL Redis, REAL MCP/ACP/LSP services, and REAL HTTP calls. To enable this: before every non-unit test run, the HelixAgent binary MUST build, distribute, and boot all containers per the Mandatory Container Orchestration Flow. Non-unit tests that cannot connect to real services MUST skip (not fail). Violations of this rule are critical infrastructure failures and block merge.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-04-21T00:00:00+03:00",
      "updated_at": "2026-04-21T00:00:00+03:00"
    },
    {
      "id": "CONST-031",
      "category": "Containerization",
      "title": "Authorized Remote Distribution Hosts",
      "description": "Remote distribution hosts are registered dynamically via `CONTAINERS_REMOTE_HOST_N_*` environment variables in `containers/.env` (N=1..100; iteration stops at first absent `_NAME`; the Containers module `pkg/envconfig/parser.go` is the authoritative loader). The .env file is the sole source of truth for host enrolment — no host is hardcoded in HelixAgent source, tests, challenges, or governance documents. Every non-unit test run and every production deployment MUST use whichever hosts are currently configured when `CONTAINERS_REMOTE_ENABLED=true`. Adding, removing, or modifying a host means editing `containers/.env`; no code change is required. The CURRENT configured set can be audited with `grep '^CONTAINERS_REMOTE_HOST_' containers/.env`; at the time of this rule's introduction (2026-04-21) the configured hosts were `thinker.local` and `amber.local`, but the rule applies to whatever set is in `.env` at any future point (N>=1). Direct `docker`/`podman` commands, manual container start/stop, and ad-hoc remote hosts outside the `.env` mechanism are strictly prohibited per the Mandatory Container Orchestration Flow.",
      "mandatory": true,
      "priority": 1,
      "added_at": "2026-04-21T00:00:00+03:00",
      "updated_at": "2026-04-21T00:00:00+03:00"
    }
  ],
  "updated": "2026-04-21T00:00:00+03:00",
  "total_rules": 31
}