Governance Roadmap¶
NON-NORMATIVE. This is an operational roadmap. Normative rules are in morphism-kernel.md.
Phased rollout with entry/exit criteria and responsible team. Targets align with the Operational Tenets (MORPHISM.md §4) tenets.
%% Governance phase progression timeline
flowchart LR
P1[Phase 1: Foundation]:::done --> P2[Phase 2: Enforcement]:::done
P2 --> P3[Phase 3: Automation]:::done
P3 --> P4[Phase 4: Observability]:::done
P4 --> P5[Phase 5: Certification]:::done
classDef done fill:#2d6a4f,color:#fff
classDef current fill:#e9c46a,color:#000
Phase 1: Foundation (Done)¶
Goal: Root governance docs, single backlog, basic CI.
| Criterion | Target | Responsible |
|---|---|---|
| AGENTS.md, SSOT.md, GUIDELINES.md | Present and referenced | @platform-team |
| docs/operations/deferred-work.md | Single deferred-work backlog | @platform-team |
| CI workflow | TS + Python lint, typecheck, test, build | CI |
| Branch protection | PR required for main | @platform-team |
Exit: All merge via PR; CI runs on every PR.
Phase 2: Enforcement (Done)¶
Goal: Commit grammar, branch naming, hooks, drift and SSOT verification.
| Criterion | Target | Responsible |
|---|---|---|
| .githooks/ | commit-msg, pre-commit, pre-push, post-merge | @platform-team |
| validate_commit.py, validate_branch.py | Enforce grammar and branch pattern | CI + hooks |
| policy_check.py | Orchestrates checks (pre-commit, pre-push, ci) | CI |
| drift-check.yml | drift_detector, validate-registry, ssot_verify, docs_sync --check | CI |
| docs/ssot/ | registry.json, atoms/*.md | @platform-team |
Entry: Phase 1 complete.
Exit: No merge when SSOT or drift check fails; hooks run locally.
Phase 3: Automation (Done)¶
Goal: Docs workflow, security scan, release pipeline, labeler, stale, notifications.
| Criterion | Target | Responsible |
|---|---|---|
| docs.yml | MkDocs build, docs_graph --check, deploy to Pages | CI |
| security.yml | Credential scan, policy_check, npm audit | @security-team |
| release.yml | Tag-triggered release | @platform-team |
| labeler.yml, stale.yml, notify.yml | Auto-label, stale management, failure webhook | @platform-team |
| .gitlab-ci.yml | Mirror of GitHub Actions | CI |
morphism scaffold tier |
CLI scaffolds Tier 1/2/3 governance files for any project | @platform-team |
.morphism/templates/ |
Template library: 25 templates (docs, projects, GitHub, CI workflows) | @platform-team |
.morphism/prompts/workspace-prompts.md |
Portfolio-wide prompt library | @platform-team |
.morphism/workflows/ |
Repo onboarding + workspace governance workflows | @platform-team |
MCP template_apply + workspace_audit |
MCP tools for template application and multi-repo audit | @platform-team |
Entry: Phase 2 complete.
Exit: Docs deploy on push to main; security runs on PR and weekly; release on tag. Scaffold tier generates governance files for any repo.
Status (2026-02-27): All criteria met. docs.yml deploys on push; security.yml scans PRs; release.yml publishes on tag; labeler.yml, stale.yml, notify.yml all active; scaffold tier CLI ships in @morphism-systems/cli v0.1.3; 17+ templates in .morphism/templates/; workspace_audit MCP tool operational. .gitlab-ci.yml mirror deferred (GitHub-only org).
Phase 4: Observability (Done)¶
Goal: Maturity score as CI gate; dashboards; backlog staleness enforced.
| Criterion | Target | Responsible |
|---|---|---|
| maturity_score.py | 0–100 score; --ci --threshold N blocks merge | CI |
| Backlog stale check | P0/P1 older than N days fail CI | CI |
| Observability | Sentry, alert rules, staging smoke (per TODO) | @sre-oncall |
Entry: Phase 3 complete.
Exit: Maturity threshold (e.g. 60) required to pass; backlog triaged.
Status (2026-02-27): All criteria met. maturity_score.py runs in ci.yml and drift-check.yml with --threshold 60 (current score: 124/125). backlog_stale.py runs in ci.yml (P0 max 7d, P1 max 14d). Sentry configured with 3 alert rules; staging smoke passes.
Phase 5: Certification (Done)¶
Goal: External audit readiness; ADR history; runbook coverage.
| Criterion | Target | Responsible |
|---|---|---|
| ADR | docs/adr/ with template and key decisions | @platform-team |
| Runbooks | docs/runbooks/ incident-response and ops | @sre-oncall |
| Worked example | End-to-end governance walkthrough in docs | @platform-team |
| verify_pipeline.py | Validates workflows, hooks, registry, CODEOWNERS | CI |
Entry: Phase 4 complete.
Exit: New joiners can follow worked example; pipeline verification in CI.
Status (2026-02-27): All criteria met. 9 ADRs in docs/adr/ (000-template through 009-deployment-pipeline). 4 runbooks in docs/runbooks/ (deployment, governance-drift, incident-response, repo-normalization). Worked example at docs/governance/worked-example.md. verify_pipeline.py runs in ci.yml integration gate.
Formal verification (roadmap)¶
Formal verification (e.g. Lean 4) of invariants and theory is tracked in PROOF_ROADMAP.md (archived). Until proof artifacts exist, claims use "design target" / "framework" wording.