Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xcoder-es/governance-layer/llms.txt

Use this file to discover all available pages before exploring further.

Governance Layer is a pre-alpha research prototype. The theoretical framework has undergone five rounds of adversarial review; the reference implementation is under active construction. Contributions are welcome — open an issue first to discuss your idea, then follow the workflow below. Expect interface churn as the theory evolves.
All participants are expected to follow the project’s Code of Conduct, which is adapted from the Contributor Covenant v2.1. Harassment-free participation is a requirement, not a suggestion.

​
Contribution workflow

1

Open an issue

Before writing any code, open a GitHub issue to describe what you want to change. This is especially important for theoretical contributions — changes that touch the formal framework (parliament, contracts, identity layer) need discussion before implementation.
2

Fork and branch

Fork the repository and create a branch named after your issue:
git checkout -b issue-42-fix-speaker-budget
The convention is issue-{number}-{short-description}.
3

Make your changes

Follow the code standards described below. All public functions need type hints. No neural networks in governance code — the layer must remain fully algorithmic.
4

Run the tests

Run the full test suite locally before opening a PR:
pytest tests/ -v
To run with coverage reporting:
pytest tests/ -v --tb=short --cov=src.governance --cov-report=term-missing
5

Submit a pull request

Open a PR against main. Reference the issue number in the PR description. Use conventional commit messages: feat:, fix:, docs:, refactor:, test:, chore:.

​
Test suite

Tests live in tests/ and cover the core governance modules. The suite is intentionally varied — unit tests, integration tests, property-based tests, and fuzz tests are all present.
FileWhat it covers
test_committee.pySeven parliament member implementations
test_contracts.pyUlysses Contract lifecycle and enforcement
test_fuzz.pyFuzz inputs to governance protocol boundaries
test_identity.pyIdentity Layer tiers, commitments, and vectors
test_integration.pyFull speaker → parliament → identity pipeline
test_property.pyHypothesis-based property tests
test_speaker.pySpeaker state machine transitions
test_tee.pySimulated TEE enclave and watchdog

​
Property and fuzz tests

test_property.py uses Hypothesis to generate adversarial inputs automatically. test_fuzz.py applies structured fuzzing to the protocol boundaries. These tests are especially important for catching edge cases in the budget and veto logic that unit tests alone do not exercise. 
# Run only the property tests
pytest tests/test_property.py -v

# Run only the fuzz tests
pytest tests/test_fuzz.py -v

​
CI pipeline

The GitHub Actions workflow (.github/workflows/tests.yml) runs on every push and pull request to main. It tests against Python 3.10, 3.11, and 3.12 in parallel. Each matrix job:
  1. Checks out the code
  2. Installs uv
  3. Runs uv sync to install all dependencies
  4. Installs the package in editable mode with uv pip install -e .
  5. Runs the full test suite with coverage: 
    uv run pytest -v --tb=short --cov=src.governance --cov-report=term-missing
  6. Uploads the .coverage artifact for inspection
All three Python versions must pass before a PR can be merged.

​
Coverage configuration

Coverage is measured over src/governance with several directories excluded. The exclusions reflect intentional scope — these modules are either experimental scaffolding or UI code that requires a running service to test meaningfully. Excluded from coverage measurement:
  • src/governance/experiments/*
  • src/governance/benchmarks/*
  • src/governance/dashboard/*
  • src/governance/ontology/*
  • src/governance/tee/*
  • src/governance/dsl/*
  • src/governance/prove/*
  • Selected identity extension files (extension.py, keys.py, ontology.py, params.py)
  • src/governance/runner.py
If you add a new module outside these paths, it will automatically appear in coverage reports.

​
Code standards

Type hints

All public functions and methods must have complete type annotations. The CI does not currently enforce this with a linter, but PRs without type hints will be asked to add them.

No neural networks

Governance code must remain fully algorithmic — no torch, no gradients, no learned parameters. The gradient barrier is a core property of the formal model.

No inline comments

Let the code speak. Use docstrings for public APIs; do not add inline # comments explaining what the code does.

Import order

Standard library → third-party → local, with one blank line between groups. Follow this strictly to keep diffs clean.

​
Issue labels

LabelMeaning
bugSomething isn’t working
enhancementNew feature or request
documentationDocs improvements
good first issueGood for newcomers
testingTest coverage
researchTheoretical or experimental
osfOSF preregistration related
bookBook chapter or appendix
cleanupRefactoring, technical debt
metaProcess / project management

​
Reporting bugs and theoretical issues

Open a GitHub issue for:
  • Bugs — unexpected errors, incorrect outputs, test failures
  • Theoretical concerns — gaps in the formal model, counterexamples to stated properties, proposed changes to the parliament or contract formalism
For theoretical contributions, reference the relevant book chapter and section. The formal framework is the foundation everything else is built on — changes there require the most scrutiny.

Build docs developers (and LLMs) love

Get started for freeTalk to us