PHPackages milpa/governance - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. milpa/governance ActiveLibrary milpa/governance ================ Governance-as-contract: immutable ADRs compile into a Governance Profile and an inspectable, honestly-enforced Governance Plan — an enforced gate is only honest if its mechanism actually guards the subject. v0.1.0(1mo ago)02Apache-2.0PHPPHP >=8.3CI passing Since Jul 18Pushed 2w agoCompare [ Source](https://github.com/getmilpa/governance)[ Packagist](https://packagist.org/packages/milpa/governance)[ RSS](/packages/milpa-governance/feed)WikiDiscussions main Synced 2w ago READMEChangelog (1)Dependencies (5)Versions (2)Used By (0) [ ![Milpa](https://raw.githubusercontent.com/getmilpa/core/main/art/lockup/milpa-lockup-v-color-light.svg) ](https://github.com/getmilpa) Milpa Governance ================ [](#milpa-governance) > **Governance-as-contract** for the Milpa PHP framework: immutable ADRs compile into a **Governance Profile** and an inspectable **Governance Plan**. The core law: *an enforced gate is only honest if its mechanism actually guards the subject* — the validator refuses a profile that claims `enforced` without a real, allow-listed mechanism behind it. [![CI](https://github.com/getmilpa/governance/actions/workflows/ci.yml/badge.svg)](https://github.com/getmilpa/governance/actions/workflows/ci.yml)[![Packagist](https://camo.githubusercontent.com/37542e2018e00d36a7819b5ce25ad9902d9d7b5239f8ec3e440032c547aec9ca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d696c70612f676f7665726e616e63652e737667)](https://packagist.org/packages/milpa/governance)[![PHP](https://camo.githubusercontent.com/ca03f11ea27dac4dedc8ad56a7bdfc4a9ff5feb825055f9d2983616115076607/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135253230382e332d3737376262342e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/798509b4df525f56802b56f8096862487f08023e3d7561c68656f8dab10d0d6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302d626c75652e737667)](LICENSE)[![Docs](https://camo.githubusercontent.com/c6dc6a3411e15b0ac7cc4583e8e6a8144181caedb82f5d98753353decda06d77/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d4150492532307265666572656e63652d626c75652e737667)](https://getmilpa.github.io/governance/) `milpa/governance` answers one question honestly: does this system's declared law actually enforce itself, or is `enforced` just a label? It takes the full corpus of immutable, ADR-backed `GovernanceDecision` objects plus the `GovernanceProfile` that names which of them currently govern, and produces two things: a **verdict** (`GovernanceValidator::validate()` throws a `GovernanceException` the instant a claim is unproven — a duplicate decision id, a dangling `supersedes`, a supersession cycle, a reference to a decision that is `rejected` or `superseded`(declared or derived), or an `enforced` gate — the profile's own or one declared inside an ADR's policies — with no allow-listed `boundTo`) and a **plan** (`GovernanceCompiler::compile()`derives the honest `GovernancePlan` — decisions, rules, gates, and required artifacts — from that same corpus). Supersession is *derived*, never mutated: an ADR file stays `accepted` forever; ending up `superseded` is a calculated effect of the plan, so the audit trail never lies about what a decision's file actually said. Install ------- [](#install) ``` composer require milpa/governance ``` What it is (and isn't) ---------------------- [](#what-it-is-and-isnt) Milpa Governance is the **engine**: it validates and compiles a governance contract you give it — an array of `GovernanceDecision` value objects plus a `GovernanceProfile`. It is **pure**: no I/O, no wall clock, deterministic (the same input compiles to the same `GovernancePlan`, byte for byte). It does **not** read files: a host implements `GovernanceRepositoryInterface` (`decisions(): array`, `profile(): GovernanceProfile`) to load a `.milpa/governance/` directory — ADRs plus a `profile.json` — and hands the resulting objects to the engine. Quick example ------------- [](#quick-example) ``` use Milpa\Governance\GovernanceCompiler; use Milpa\Governance\GovernanceValidator; // $repository implements GovernanceRepositoryInterface — the host already loaded // .milpa/governance/ (ADRs + profile.json) and handed the engine objects, not files. $decisions = $repository->decisions(); // array $profile = $repository->profile(); // GovernanceProfile $validator = new GovernanceValidator(GovernanceValidator::DEFAULT_BOUND_TO); $validator->validate($decisions, $profile); // throws GovernanceException if the profile lies $plan = (new GovernanceCompiler($validator))->compile($decisions, $profile); $plan->profileName; // the profile's name $plan->gates; // array — this contract's honest gates $plan->toArray(); // deterministic, serializable shape ``` `compile()` calls `validate()` first — a plan is never built from an unproven contract — then derives, from the **full** decision corpus (including superseded and historical lineage, so the plan can show it honestly): one `GovernanceRule` per active decision, the merged `GovernanceGate`s and `RequiredArtifact`s (from the profile itself and from `kind: 'gate'` / `kind: 'artifact'` policies declared inside each ADR), and a `planHash` that binds this exact compilation. A `rejected`, `proposed`, or `deprecated` decision never enters the plan — not as a decision entry, and none of its policies govern anything. The value objects ----------------- [](#the-value-objects) Value objectRole`GovernanceDecision`An immutable ADR: `id`, `title`, `DecisionStatus` (`proposed`|`accepted`|`rejected`|`superseded`|`deprecated`), what it `supersedes`, what it `governs`, its derived `policies`, and a `contentHash` that seals its content.`GovernanceProfile`The law's table of contents: the `decisionIds` that currently govern, the typed `GovernanceGate`s and `RequiredArtifact`s, and the profile's own `schemaVersion`/`name`/`version`.`GovernanceGate`A checkpoint: an `id`, a `description`, an `EnforcementTier` (`enforced`|`advisory`|`convention`|`deferred`), and the `boundTo` mechanism an `enforced` gate must name to be honest.`GovernancePlan`The compiled, inspectable law: decisions (with derived `effectiveStatus`/`supersededBy`), rules, gates, artifacts, actors, assumptions, and the `planHash` that binds the whole compilation. `toArray()` is the deterministic, serializable shape.`GovernanceManifest`The `{id: contentHash}` immutability seal, ksorted and hashed — `verifyIntegrity()` detects drift against the current hashes, `immutabilityViolations()` detects a decision that changed or disappeared since a prior base manifest.`GovernanceException`Every contract break, one named factory per cause (`profileMissing`, `decisionDuplicate`, `supersessionCycle`, `enforcementUnproven`, …) — each message names what broke, why, and the fix.Anatomy of a governance contract -------------------------------- [](#anatomy-of-a-governance-contract) A contract lives in `.milpa/governance/`: immutable ADRs (`adr/*.md`) plus a `profile.json`. The engine consumes them through the host's `GovernanceRepositoryInterface` — it never reads the directory itself. This is the minimal shape (generic — an example service, not any real repo's law): **`.milpa/governance/adr/0001-tests-are-the-contract.md`** ``` --- id: ADR-0001 title: Tests are the contract status: accepted date: 2026-01-15 supersedes: null governs: [quality] policies: [] --- ## Context A green suite is the cheapest proof that a change didn't break the promise. ## Decision Every change ships with the test suite green. The `tests` gate is `enforced`, bound to the CI job that actually runs it. ## Consequences An `enforced` gate with no real job behind it would be a lie the validator rejects. ``` **`.milpa/governance/profile.json`** ``` { "schemaVersion": "0.1", "name": "example-service", "version": "2026.01.1", "decisionIds": ["ADR-0001"], "gates": [ { "id": "tests", "description": "The test suite passes.", "tier": "enforced", "boundTo": "ci:test:unit" } ], "artifacts": [], "actors": [] } ``` Compiling this contract yields a `GovernancePlan` whose `tests` gate is honestly `enforced` because `ci:test:unit` is an allow-listed mechanism (`GovernanceValidator::DEFAULT_BOUND_TO`). Change `boundTo`to something not on the allow-list and `validate()` throws — the wall that stops an aspirational gate. Requirements ------------ [](#requirements) - PHP **≥ 8.3** - No runtime dependencies — the engine is dependency-free by design (`milpa/core` is a dev-only dependency, used solely to generate the API reference). Documentation ------------- [](#documentation) **Full API reference: [getmilpa.github.io/governance](https://getmilpa.github.io/governance/)** — generated straight from the source DocBlocks and dressed with the Milpa design system. Contributing ------------ [](#contributing) Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please report security issues via [SECURITY.md](SECURITY.md), and note that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md). License ------- [](#license) [Apache-2.0](LICENSE) © Rodrigo Vicente - TeamX Agency. --- Milpa is designed, built, and maintained by **[Rodrigo Vicente - TeamX Agency](https://teamx.agency/?utm_source=github&utm_medium=readme&utm_campaign=milpa&utm_content=governance)**. ### Health Score 37 — LowBetter than 81% of packages Maintenance94 Actively maintained with recent releases Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 46d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/1993784?v=4)[rodrigomx](/maintainers/rodrigomx)[@rodrigomx](https://github.com/rodrigomx) --- Top Contributors [![rodrigoteamx](https://avatars.githubusercontent.com/u/269849276?v=4)](https://github.com/rodrigoteamx "rodrigoteamx (7 commits)") --- Tags adrarchitecture-decision-recordsauditcomplianceframeworkgovernancemilpaphp ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/milpa-governance/health.svg) ``` [![Health](https://phpackages.com/badges/milpa-governance/health.svg)](https://phpackages.com/packages/milpa-governance) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)