Skip to content

Code Hygiene

Jump to bottom
Paul Rigor edited this page Jun 25, 2026 · 1 revision

Code Hygiene

ADEPT's Code Hygiene conventions were distilled from 100+ development sessions into a reproducible, evidence-based workflow. This page covers branch strategy, testing requirements, commit format, and the documentation chain that ties every change back to its context.

Branch Strategy

Branches follow a hierarchical naming convention encoding fiscal quarter, work stream, and scope:

<category>-<workstream>-<FY-quarter>-<scope>

Examples:
  feature-platform-optimizations-FY26Q4-phase1
  bugfix-auth-FY26Q4-jwt-expiry
  refactor-orchestration-FY26Q4-simplify-routing

Parent-Child Hierarchy

Work streams branch from a parent feature branch, not directly from main:

main
 +-- feature-platform-optimizations-FY26Q4              (parent)
      +-- feature-...-phase1                             (child: current work)
      +-- feature-...-add-slurm-cobrapy                  (child: HPC integration)
      +-- feature-...-validate-connectors                (child: connector hardening)

Merge Strategy

Direction Method Reason
Child to parent Fast-forward merge Preserves individual commit history
Parent to main Squash-merge via PR Clean public release history
Main to phase branch Forward-merge Updates merge-base for future PRs

Testing Strategy

Test Tiers

Tier Scope When Required Example
Unit Single function/class, no external deps Every code change make validate-unit-contract-tests
Integration Cross-component with real services Feature changes make validate-integration-batch-file-operations
E2E Full stack through API API/routing changes make validate-e2e-rag-workflow
UAT Container-based acceptance Connector/UI changes make test-uat-container
Contract Attribute existence + method execution New/modified classes make validate-unit-contract-tests

Tier Selection Matrix

Changed Files Required Tiers
src/ Unit tests mandatory
Cross-package Integration required
API routes / gateway E2E required
Connectors / UI All 4 tiers
examples/adept_connectors/ All 4 tiers (306 tests)
Docs only No tests needed
IaC Dry-run validation

Mandatory Test Execution Pattern

All test invocations MUST use nohup with timestamped log files:

mkdir -p logs && nohup make validate-<target> \
  > logs/<scope>_$(date +%Y%m%d_%H%M%S).log 2>&1 &

This ensures tests run to completion even if the terminal drops, and preserves timestamped evidence for the commit message.

Container-Based Execution

All tests run inside Docker containers:

docker run --rm \
  --network=adept_application_network \
  --network=adept_frontend_network \
  -v "$(pwd)/src":/app/src:ro \
  -v "$(pwd)/tests":/app/tests:ro \
  agentic-framework-deps-base \
  /app/.venv/bin/pytest tests/unit/<path> -v --tb=short

Rules:

  • Always use :ro (read-only) for source/test mounts
  • Use dual networks: adept_application_network + adept_frontend_network
  • Never use --network=agentic_framework_network (deprecated)
  • Never run pytest directly on the host

Rebuild Before Test

If any src/ files changed, rebuild affected containers BEFORE running integration or E2E tests:

Source Path Service Rebuild Command
orchestration_service/ orchestration_service make rebuild-orchestrator
agent_gateway/ agent_gateway make rebuild-gateway
gateway_registry/ gateway_registry make rebuild-registry
mcp_server/ mcp_server make rebuild-mcp
sandbox_mcp_server/ sandbox_mcp_server make rebuild-sandbox-mcp

Commit Strategy

Conventional Commits

All commits use the Conventional Commits format:

<type>(<scope>): <short description>
Type When to Use
feat New features
fix Bug fixes
docs Documentation-only changes
refactor Code restructuring without behavior change
test Test-only changes
chore Maintenance (lock files, dependencies)
ci CI/CD pipeline changes
perf Performance improvements
build Build system changes

Commit Message Body

type(scope): one-line summary (imperative mood, <=72 chars)

2-5 line paragraph explaining WHAT changed and WHY.

Related documentation (this commit):
- docs/implementation-reports/SESSION_N_TITLE.md
- docs/CHANGELOG.md (Session N entry)

Related documentation (past 5 commits):
- docs/implementation-reports/SESSION_N-1_TITLE.md (abc1234)
- docs/bugfixes/SESSION_N-2_TITLE.md (def5678)

The two "Related documentation" sections create a documentation chain where any commit can be understood by following references forward and backward.

Pre-Commit Evidence Gate

No code commit without test evidence. Before staging src/ or examples/ files:

  1. Timestamped test logs in logs/ MUST be newer than source modifications
  2. Logs MUST be relevant to the changed code paths
  3. Logs MUST show passing results

Exempt: commits modifying only docs/, .claude/skills/, or configuration files.

What NOT to Commit

  • .env files with real secrets
  • Credential files from .env-keycloak-credentials-dir/
  • Large binary files (model checkpoints, data files)
  • Temporary logs/ files
  • __pycache__/ directories
  • AI agent attribution (no Co-Authored-By for Claude/Gemini/ChatGPT/Copilot)

Documentation Strategy

Per-Session Documentation

Every session that produces code changes generates:

Document Location Purpose
Implementation report or bugfix doc docs/implementation-reports/ or docs/bugfixes/ Detailed technical record
CHANGELOG entry docs/CHANGELOG.md Chronological summary
ROADMAP entry docs/ROADMAP.md "Recently Completed" section
KNOWN_ISSUES updates docs/KNOWN_ISSUES.md New issues discovered or resolved

Documentation Tiers

Tier Location Content
1 docs/*.md High-level navigation, 2-5 sentence summaries with links
2 docs/PLATFORM_*.md, docs/DOMAIN_*.md Onboarding guides, HOWTOs
3 Subdirectories (docs/architecture/, etc.) Detailed implementation, test results

Code Style

Tool Purpose Configuration
Black Code formatting --line-length 88
isort Import sorting --profile black
ruff Linting --target-version py311
mypy Type checking --ignore-missing-imports

Run order: Black first, isort second, ruff third, mypy last. All run via Docker containers for consistency.

Quick Reference Checklist

Before every push, verify:

  • Branch named correctly (<type>-<scope>-<quarter>-<description>)
  • Required test tiers pass (timestamped evidence in logs/)
  • Affected service containers rebuilt (newer than source changes)
  • Code formatted (Black + isort)
  • No linting errors (ruff)
  • Conventional Commit message with Related Documentation footer
  • Session report exists (if code changes)
  • CHANGELOG updated (if user-facing change)
  • No secrets or credentials in staged files
  • No AI agent attribution in commit message

Related Pages

Home

Getting Started

Architecture

Deployment

User Guides

Developer Tools

CI/CD

Testing

Contributing

Reference

Clone this wiki locally