ERIC'S ENGINEERING CONSTITUTION V1.48.1

Eric's Engineering Constitution

A standardized framework ensuring rigor, security, and automated verification across software projects for humans and AI agents alike.

Validation Pillars 12 Principles Workflow Simulator

What is the Constitution?

Eric's Engineering Constitution is a reusable governance framework pinned to repositories as a Git submodule. It aligns human contributors and autonomous AI agents under identical, high-standard software engineering behaviors—governing code quality, documentation, testing, and operations.

Why does it exist?

While AI agents accelerate development, they can introduce code drift, bypass regression tests, omit critical documentation, or leak secrets. The Constitution enforces continuous rigor by gating pull requests through automated compliance tools—ensuring every change is verified, safe, and fully documented.

Eric's Engineering Constitution Infographic visual representation
Interactive Preview

Framework Blueprint & Collaboration Paradigm

Click to expand the high-resolution infographic summarizing the Constitution pillars and AI-Pair-Programming architecture.

The Compliance Validation Triad

The framework relies on a three-legged FDA-style tracking and validation triad. It establishes automated CI gates and local scripts to ensure that nothing reaches production without documentation, tests, and dependency risk checks.

1. Traceability

Requirement to verification tracking

2. Test execution

Full test suite enforcement

3. OTS Inventory

Third-party dependency scanner

Requirements Traceability Matrix

Enforces a mapped connection from stable requirement IDs (e.g. FR-012) to automated verification tests. Substring collisions are detected by CI to block invalid compliance states.

$ bash constitution/scripts/check_traceability.sh
Scanning docs/PRODUCT_REQUIREMENTS.md for requirement IDs...
Found 12 functional requirements (FR-001 through FR-012)
Scanning docs/REQUIREMENTS_TRACEABILITY.md for matching verification...
Reconciling tests in tests/test_*.py ...
[OK] FR-001 -> verified by tests/test_auth.py:test_login_lockout
[OK] FR-012 -> verified by tests/test_processor_sop.py:test_regression
Traceability Matrix verification matches 100% of defined specifications.

Automated Test Suite Enforcement

CI runs `run_declared_tests.sh` which dynamically parses and executes the verified test command declared inside docs/TEST_PLAN.md. A test failure blocks PR merging.

$ bash constitution/scripts/run_declared_tests.sh .
Found test plan: docs/TEST_PLAN.md
Declared runner command: "npm run test:ci"
Executing: npm run test:ci ...
PASS tests/auth.test.ts (8.2s)
PASS tests/compliance.test.ts (2.4s)
PASS tests/secrets.test.ts (1.1s)
✔ All 45 tests passed.
Test suite run succeeded. Exiting 0.

OTS Software Inventory & Risk Review

Enforces recording and reviewing all third-party dependencies (runtimes, databases, libraries) in docs/OTS_SOFTWARE.md. `check_ots_inventory.sh` flags any newly added package missing in the inventory.

$ bash constitution/scripts/check_ots_inventory.sh .
Parsing local package manifests... (package.json, pyproject.toml)
Comparing packages against docs/OTS_SOFTWARE.md inventory...
[VERIFIED] lodash -> OTS-001 (Version: 4.17.21, Risk: Low)
[VERIFIED] fastify -> OTS-002 (Version: 4.21.0, Risk: Medium)
[OK] All 12 runtime dependencies exist in OTS inventory.
OTS software check passed. No undocumented dependencies found.

Interactive Workflow Simulator

Watch the AI agent transition through the 30 mandatory workflow steps. This ensures proper alignment, checkpoints, and documentation before code changes are made.

Step 1 of 5
Phase 1: Initial Hook
1. Claude Session Start hook triggered
The session start hook scans the repository submodule to verify compliance and updates version status. If the submodule pointer lags the latest release tag, instructions on remediation are injected directly into context.
Phase 2: Planning & Crash Recovery
8 & 10. Write docs/SESSION_PLAN.md
Before any code is altered, the agent creates a session plan mapping goals, approaches, file diff boundaries, and risks. This serves as a recovery record should the session crash or get interrupted.
Phase 3: Implementation Loop
12 & 13. Implement changes & Execute declared tests
Code edits are applied. The agent runs `run_declared_tests.sh` locally to run the exact test commands defined in the test plan to ensure no regressions occur.
Phase 4: Pre-Commit Sweep
25. Secrets Sweep before push
The agent runs `check_secrets.sh` locally. It scans both tracked and untracked files for credential shapes and high-confidence regex patterns, blocking the push if a secret is found.
Phase 5: Session Termination
23. Clear/Archive Session Plan
With work successfully verified, the final changes are recorded in the changelog and the roadmap is updated. The session plan is cleared, allowing the next session to overwrite it.

12 Core Principles

Click on any principle to inspect its operational code smell and required guardrail.

Principle 1
Docs are Deliverables

All changes must consider documentation impact. Readme and session planning are mandatory.

Principle 2
Testing is Required

All new functionality and bug fixes include automated tests mapped to requirement IDs.

Principle 3
TODO Management

Maintain TODO.md as the living roadmap. Log debt, feature opportunities, and refactoring.

Principle 4
Continuous Improvement

Agents actively identify UI, UX, speed, reliability, and developer experience improvements.

Principle 5
Security Controls

Enforce input validation, least privilege, local secret sweeps, and protocol firewalls.

Principle 6
Architecture Awareness

Record major frameworks and database structures in Architecture Decision Records (ADRs).

Principle 7
Dependency Hygiene

Prefer mature packages. Document dependencies in the OTS software inventory.

Principle 8
Observability by Design

Log diagnoses cleanly, avoid leaking credentials, and create clear operational logs.

Principle 9
Operations Discipline

Operational changes must be reviewable, observable, and recoverable with a runbook.

Principle 10
Release Discipline

SemVer enforcement. Bump versions on VERSION and push Git tags for each release.

Principle 11
Opportunity Discovery

Agents look beyond immediate tasks to recommend future architectures and tools.

Principle 12
Official Code Conventions

Style guides and docstring formats must follow language owners' official styling rules.

High Resolution Infographic