Repository navigation
v0.2.0
Immutable
release. Only release title and notes can be modified.
0.2.0 (2026-09-11)
Governance impact
Phase: + ▣ P1 — phase governance introduced
Items: 62 introduced · 16 superseded
Introduced · 62
| GV | Proposition |
|---|---|
| + GV0 ✓ | Literate Govenv.lagda.md closure root. |
| + GV1 ✓ | Project governance under Govenv/; reusable kernel under Govenv.Kernel.*. |
| + GV2 ✓ | Reproducible Stage 0 bootstrap, documentation site, and automated releases. |
| + GV3 ✓ | Verdict: holds, violated, and unknown. |
| + GV4 ✓ | Minimal Rule abstraction. |
| + GV5 ✓ | Typed repository facts. |
| + GV6 ✓ | Dependency-indexed rules. |
| + GV68 ✓ | Type roadmap governance identifiers as GovernanceId and use readable ✓/◇ item notation instead of raw Nat plus done/todo. |
| + GV69 ✓ | Make roadmap phase progression structurally valid with exactly one active phase while in progress, declare phases with ■/▣/□, and render phase/item state using the same operator glyphs. |
| + GV50 ✓ | Use generic typed identifiers with structural BelongsTo, and express the entire roadmap as one declarative tree with implementation mechanics hidden. |
| + GV52 ✓ | Enforce roadmap identity and completion integrity: phase and governance indices must be unique, phase indices must progress monotonically, and a finished phase may contain no pending governance items. |
| + GV57 ◇ | Inventory repository behavior and policy, distinguishing governed semantics from irreducibly observational or effectful mechanisms. |
| + GV58 ◇ | Require every inventory entry whose semantics can be expressed and checked by Govenv to be backed by governed data and a rule. |
| + GV59 ◇ | Minimize the ungoverned surface to irreducible observation and effect execution; adapters may perform effects but must not introduce semantic content, policy, structure, ordering, or authorization decisions. |
| + GV62 ◇ | Enforce architecture roles and dependency directions for the closure root, constitution, materialization, kernel, projection, adapters, and generated artifacts. |
| + GV20 ✓ | Keep Govenv as the canonical immutable project identity; white-label distributions may change branding projections, never the Govenv identity. |
| + GV60 ✓ | Govern README.md as the canonical output of Govenv.Materialization.Readme; manual divergence must fail the project check. |
| + GV15 ✓ | Keep the README roadmap projection to exactly two visible levels, Phase → Item, with phases collapsible. |
| + GV16 ✓ | Materialize governed README sections from Agda rather than maintaining duplicate prose by hand. |
| + GV51 ✓ | Materialization closure: every state materialized by Govenv must have exactly one canonical Govenv.Materialization.* definition containing all semantic content, structure, ordering, inclusion, policy, and required capability decisions; projections encode only target-format representation, and adapters only observe, apply, or verify effects. |
| + GV18 ◇ | Allow versioned materializations to follow their governing source change in the immediately subsequent chore(materialize) commit; the final pushed or reviewed state must contain canonical materializations. |
| + GV19 ✓ | Require CI validation and publication workflows to materialize governed artifacts from the constitution and reject any resulting tracked drift before continuing. |
| + GV21 ✓ | Project the canonical Govenv description from Govenv.Project into repository-facing materializations. |
| + GV22 ✓ | Require admin-privileged external materializations to run only through the manual, target-restricted Admin Materialize workflow. |
| + GV45 ✓ | Require every admin materialization to read the target back after applying it, fail unless the observed value equals the governed expected value, and emit execution evidence tied to the constitution SHA, target, repository, and workflow run. |
| + GV46 ◇ | Model admin materialization evidence as typed governed data that can be consumed by a formal rule or assurance check rather than relying on workflow success alone. |
| + GV63 ◇ | Close the GitHub Actions portion of the governance inventory: triggers, permissions, concurrency, runners, timeouts, pinned actions, Nix runtime/cache, materialization, tests, Pages, releases, and admin boundaries. |
| + GV24 ◇ | CI projection closure rule: GitHub Actions workflows must contain no independent policy; every CI behavior must be traceable to governed project data and ultimately materializable from the constitution. |
| + GV12 ◇ | CI governance rule: Govenv CI must run on Determinate Nix; changing the Nix runtime requires an explicit governance change. |
| + GV13 ◇ | CI cache governance rule: every Govenv CI workflow that evaluates or builds Nix must use a local GitHub Actions Nix cache through magic-nix-cache-action; removing or replacing it requires an explicit governance change. |
| + GV44 ✓ | Automatically apply versioned non-admin materializations on main using only repository-scoped CI permission; validation and publication workflows run after Materialize completes, while admin materializations remain manual. |
| + GV70 ✓ | Project release governance deltas from immutable typed roadmap snapshots and commit references, distinguishing introduced, advanced, completed, cancelled, and superseded items plus phase progression while rejecting identity mutation or removal and keeping SemVer independent. |
| + GV54 ✓ | Preserve immutable governance identity across roadmap evolution: once introduced, a GovernanceId, its definition, and its owning phase may never be removed, reused, or modified; obsolete or corrected governance must remain represented as cancelled or superseded, with supersession explicitly identifying a newer replacement GovernanceId. |
| + GV71 ◇ | Restrict handwritten versioned repository content to Agda and Markdown only. Any generated or governed materialization may use its required target format. Until GV38 is completed, the only handwritten bootstrap escape hatch is root-level devenv.nix, devenv.yaml, and devenv.lock; all other implementation languages and handwritten configuration formats, including Nix elsewhere, are forbidden. |
| + GV72 ◇ | Require every versioned repository artifact not permitted as handwritten source by GV71, except the temporary root-level devenv.nix, devenv.yaml, and devenv.lock bootstrap escape hatch, to be produced by exactly one governed Govenv.Materialization.* definition and verified against its materialized state; transient .govenv state is forbidden from being versioned. |
| + GV73 ◇ | Require every persisted supporting artifact, including snapshots, fixtures, baselines, schemas, test vectors, and evidence, to be colocated with the module that semantically owns it; catch-all artifact directories are forbidden unless the artifact is genuinely project-global. |
| + GV74 ◇ | Make governance completion evidence-bearing and persistent: a governance item may transition to done only when governed evidence establishes its proposition for the candidate repository state, and every non-superseded done item, including items completed before this rule, must remain satisfied in every subsequent valid repository state. |
| + GV75 ◇ | Render release governance item changes as compact semantic diffs: remove redundant per-item progress labels, align before/after propositions for supersessions, visually distinguish only changed spans, and deterministically wrap or elide common context while preserving the full typed governance delta. |
| + GV76 ◇ | Make governance references in Git-derived projections revision-aware and navigable: linked identities, lifecycle states and operators, transitions, and elisions must resolve to documentation derived from the immutable Git revision or delta they represent; before-state references use the base revision and after-state references use the candidate or head revision. |
| + GV77 ◇ | Make CHANGELOG.md the canonical versioned portable materialization of each typed release entry, while the Release Please pull request and published GitHub Release project the same typed release content through a shared enriched GitHub renderer; external GitHub Release application must be verified by read-back equality. |
| + GV55 ◇ | Model the governed release-progress policy: major and minor releases require governance progress by completing at least one pending item or advancing to a later phase; patch releases are exempt. |
| + GV56 ◇ | Encode and enforce GV55 as Govenv's first self-governing Rule over typed release governance state. |
| + GV64 ◇ | Purely evaluate facts and rules into verdicts, obligations, and typed diagnostics without IO. |
| + GV65 ◇ | Purely associate governance diagnostics with governed repository provenance so consumers can produce source-mapped diagnostics without IO. |
| + GV26 ◇ | Observe repository facts through a thin impure adapter. |
| + GV53 ◇ | Expose repository evaluation as govenv check, with deterministic exit status and source-mapped diagnostics while keeping observation and effects outside the pure evaluator. |
| + GV66 ◇ | Model governed commit policy as project data with a simplified Conventional Commits vocabulary; governance changes must use gov(...), and every governed commit must reference its related roadmap subitem(s) using a Refs: GV… footer. |
| + GV29 ◇ | Validate the staged candidate repository state using the candidate governance before accepting a commit. |
| + GV30 ◇ | Enforce commit governance transparently through a Git hook; Stage 0 installs it through devenv, and Govenv later owns the integration directly. |
| + GV31 ◇ | Recheck only rules affected by changed facts and emit diagnostic deltas. |
| + GV32 ◇ | Prove incremental checking equivalent to full checking. |
| + GV33 ◇ | Expose the checker through an LSP/editor loop. |
| + GV34 ◇ | Expose governance context and diagnostic deltas through an MCP adapter for agent clients. |
| + GV35 ◇ | Define typed Environment/Runtime IR. |
| + GV67 ◇ | Keep runtime backends replaceable behind the typed IR boundary. |
| + GV36 ◇ | Compile valid projects through a devenv backend. |
| + GV37 ◇ | Expose govenv shell, govenv test, and govenv up. |
| + GV38 ◇ | Ship a standalone govenv entrypoint and managed runtime setup. |
| + GV39 ◇ | Make Govenv govern and build itself. |
| + GV41 ◇ | Support white-label distributions while keeping the formal kernel reusable and product-neutral. |
| + GV42 ◇ | Make repository bootstrap, integrations, secrets/environments setup, and privileged materialization declarative and reproducible through Govenv rather than repository-specific manual steps. |
| + GV43 ◇ | Make the final product ejectable from the Govenv codebase: a white-label distribution must be able to carry its governed project model, generated CI/materializations, and integrations without depending on klarkc/govenv repository-specific code. |
Superseded · 16
| GV47 ↪ GV68 |
|---|
GovernanceId and use readable of raw Nat … |
GovernanceId and use readable of raw Nat … |
| GV49 ↪ GV69 |
|---|
|
state using the … |
|
state using the … |
| GV9 ↪ GV57 |
|---|
|
|
|
|
| GV10 ↪ GV58 |
|---|
|
checked by Govenv |
|
Govenv |
| GV11 ↪ GV59 |
|---|
|
|
|
|
| GV17 ↪ GV61 |
|---|
|
projection, adapters, and generated artifacts. |
|
kernel, projection, adapters, and generated artifacts. |
| GV61 ↪ GV62 |
|---|
|
materialization, kernel, projection, adapters, and … |
|
constitution, materialization, kernel, projection, adapters, and … |
| GV14 ↪ GV60 |
|---|
|
divergence must fail the project … |
|
manual divergence must fail the project … |
| GV23 ↪ GV63 |
|---|
|
timeouts, pinned … |
|
permissions, concurrency, runners, timeouts, pinned … |
| GV48 ↪ GV70 |
|---|
|
references, distinguishing completed, phase progression while keeping SemVer independent. |
|
commit references, distinguishing |
| GV7 ↪ GV55 |
|---|
|
completing at least one patch releases … |
|
later phase; patch releases … |
| GV8 ↪ GV56 |
|---|
|
|
|
|
| GV25 ↪ GV64 |
|---|
|
|
|
diagnostics without IO. |
| GV27 ↪ GV65 |
|---|
|
|
|
|
| GV28 ↪ GV66 |
|---|
|
vocabulary; … |
|
Commits vocabulary; … |
| GV40 ↪ GV67 |
|---|
| proposition unchanged |
| Keep runtime backends replaceable behind the typed IR boundary. |
Derived from immutable typed roadmap snapshots and governed Refs: GV… commit metadata. SemVer remains independent. 45895e6..0e03a8c.
Features
- kernel: model typed repository facts (adcb92a)
Governance
- admin: record verified materialization (1029e8e)
- admin: verify materialization read-back (c7b6f1c)
- assurance: gate completed governance (faa1e59)
- assurance: require candidate witnesses (b50e8ef)
- assurance: separate completion evidence (419c35c)
- ci: govern administrative bootstrap and CI projection (c8739c8)
- commits: require roadmap references (208cdd5)
- kernel: index rules by declared facts (3cda88c)
- materialization: make target semantics canonical (fc0e244)
- materialize: automate versioned projections (bbdf037)
- project: govern identity and materializations (dc2d11c)
- readme: materialize governed project readme (0975a90)
- release: clarify governance impact (ed1c61c)
- release: classify terminal introductions (37255ae)
- release: close typed release governance (b421130)
- release: decouple canonical changelog target (d18a4a3)
- release: define governance delta (bb10417)
- release: isolate release bot identity (fa9da09)
- release: project typed governance delta (8982372)
- release: render semantic governance diffs (288108c)
- release: separate canonical and GitHub projections (1664c89)
- roadmap: add MCP adapter milestone (9b7edaa)
- roadmap: add stable roadmap references (f4ce4f5)
- roadmap: adopt P and GV identifiers (19f6e56)
- roadmap: align governance phase boundaries (6e9449f)
- roadmap: distinguish active phase glyph (0a50c3b)
- roadmap: distinguish pending item glyph (8456e5b)
- roadmap: enforce roadmap integrity (942cf39)
- roadmap: govern ci cache (3f88678)
- roadmap: index governance by phase (9217340)
- roadmap: make roadmap structure intrinsic (a25ee67)
- roadmap: minimize ungoverned surface (79b8c1b)
- roadmap: preserve immutable governance history (03b2d54)
- roadmap: reflect typed facts progress (f059233)
- roadmap: require progress on major and minor releases (27dbaca)
- roadmap: restore commit governance plan (88b76ad)
- roadmap: type governance identifiers (22fd80a)
- roadmap: type phase identifiers (ef05299)
- roadmap: unify phase and item state notation (7ade94c)
Continuous Integration
- avoid flakehub cache misses (3e87730)
- keep determinate nix in actions (d91843c)
- restore local nix cache (85c632d)
- test govenv and fix nix cache setup (07951f1)
- use upstream nix in actions (a9b522c)
Miscellaneous
- materialize: update governed materializations (78923b0)
- materialize: update governed materializations (87937cb)
- materialize: update governed materializations (8531839)
- materialize: update governed readme (fdc8b9c)
- materialize: update governed readme (d91d969)
- materialize: update governed readme (389bc14)
- materialize: update governed readme (085cb76)