libzdock-project-principles

name	libzdock-project-principles
description	Project-specific engineering rules for libzdock native code, GNU Make portability, dependencies, licensing, CI, tests, and repository structure. Use for any C++ change, build or workflow change, dependency update, source branding change, native test work, or cross-language repository maintenance.
license	BSD-2-Clause
metadata	{"author":"Arjan van der Velde, Weng Lab","copyright":"Copyright (c) 2019-2026 Arjan van der Velde, Weng Lab","version":"1.0.0"}

libzdock Project Principles

Normative Language

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative.

• MUST indicates an absolute requirement.
• MUST NOT indicates an absolute prohibition.
• SHOULD indicates a strong recommendation that may be departed from only for a documented reason.
• SHOULD NOT indicates a discouraged action that may be taken only for a documented reason.
• MAY indicates an optional action.

Interpret these keywords according to RFC 2119 and RFC 8174 when they appear in uppercase.

Project Boundary

libzdock provides native PDB and ZDOCK/M-ZDOCK parsing, coordinate transformations, command-line tools, and a separate Python parser package.

Changes SHOULD remain small and explicit. New abstraction layers MUST have a concrete maintenance, safety, or reuse benefit.

Build And Portability

• The project MUST use GNU Make. It MUST NOT introduce CMake unless the user explicitly reverses this decision.
• GNUmakefile MUST remain the authoritative build. Makefile MUST remain a clear BSD-make redirect to gmake.
• The build MUST support 64-bit Linux, macOS, and FreeBSD without assuming GNU userland outside GNU Make.
• Linux documentation and CI MAY use make. macOS and BSD documentation and CI SHOULD use gmake when the platform make is not GNU Make.
• Compiler, archiver, flags, and linker settings MUST remain overridable from the command line.
• Native code MUST build warning-free with the configured GCC, Clang, and Apple Clang warning set.
• Catch2 and Eigen MUST remain pinned submodules unless the user explicitly chooses another dependency mechanism.
• Dependency updates MUST include a clean rebuild rather than relying on stale objects.

Licensing And Branding

• Project-owned files MUST use the short copyright and SPDX marker from copyright.txt.
• The project license MUST remain BSD 2-Clause unless the user explicitly changes it.
• LICENSE and python/LICENSE MUST carry the complete BSD 2-Clause text and current copyright range.
• Upstream libpdb++ notices MUST remain intact. Agents MUST NOT relabel upstream-derived files as solely BSD-2-Clause.
• Fixed-format fixtures and vendored submodules MUST remain excluded from automated license and whitespace rewriting.
• .pre-commit-config.yaml SHOULD enforce branding, syntax, whitespace, spelling, and project quality rules.

Native Correctness

• Object lifetime and copy behavior MUST use C++ value semantics rather than byte-clearing non-trivial objects.
• zdock::PDB copying MUST preserve the selected record graph and shared record identity without re-running user filters.
• Fixed-size record formatting MUST be bounded. Tests SHOULD force truncation and maximum-width paths, not only ordinary inputs.
• Intentional switch fallthrough MUST be explicit to both readers and compilers.
• M-ZDOCK transformation order and reverse-rotation compatibility MUST be treated as observable behavior.
• Coordinate and transformation tests SHOULD use independently calculated expected values rather than restating production expressions.

Testing Standards

• Every test case MUST include a nearby comment or docstring that states the invariant being tested.
• Tests MUST assert externally meaningful behavior. They MUST NOT merely describe the current implementation.
• Regression tests SHOULD fail when the motivating defect is reintroduced.
• Boundary-sensitive code SHOULD use adversarial values, malformed input, and exact edge conditions.
• Identity, ownership, copy, and model tests MUST distinguish equality of values from sharing of objects.
• Changes to native code or shared behavior MUST run a clean build, native tests, and Python integration tests.
• Safety-sensitive native changes SHOULD also run AddressSanitizer and UndefinedBehaviorSanitizer when supported locally.

Validation

Run the normal repository workflow with the platform's GNU Make command:

make clean
make -j4 all
make cpp-test
make python-test
make python-check

On systems where GNU Make is installed as gmake, substitute gmake consistently.

Before handoff, agents MUST run git diff --check and the relevant pre-commit hooks. Generated build output and caches MUST NOT be committed.