Governance
Version: 1.0
Status: Approved
Owner: Platform Architecture Team
Last Updated: 2026-04-12
References: AGENT.md §15–16, system.md §9
1. Purpose
This document defines the governance model for all platform specifications: lifecycle management, change control, approval authority, and definition of done.
2. Specification Lifecycle
Draft → In Review → Approved → Implemented → Verified → Deprecated
| Status | Meaning |
|---|---|
| Draft | Being authored; not ready for review |
| In Review | Under peer/stakeholder review |
| Approved | Formally approved; authoritative |
| Implemented | Code deliverables complete |
| Verified | Tested and confirmed compliant with spec |
| Deprecated | Superseded; retained for historical reference |
3. RACI Matrix
| Activity | Platform Architect | Service Lead | QA Lead | Delivery Manager |
|---|---|---|---|---|
| Author platform specs | R/A | C | C | I |
| Author service specs | C | R/A | C | I |
| Review all specs | A | R | C | I |
| Approve platform specs | A | C | C | I |
| Approve service specs | C | A | C | I |
| Change control decisions | A | C | C | R |
| Definition of done sign-off | C | R | A | I |
R = Responsible, A = Accountable, C = Consulted, I = Informed
4. Change Control
4.1 Minor Changes (PATCH version bump)
- Corrections to wording, assumptions, or open points that do not alter requirements.
- Author updates the document and notifies the team in the relevant PR.
- No formal approval required; reviewed as part of standard PR review.
4.2 Significant Changes (MINOR version bump)
- New requirements added, or existing requirements clarified in a way that affects implementation.
- Requires review and approval from the Service Lead (for service specs) or Platform Architect (for platform specs).
- PR must reference the changed requirement IDs in the description.
4.3 Breaking Changes (MAJOR version bump)
- Requirements removed or fundamentally changed.
- Requires formal approval from Platform Architect + Delivery Manager.
- Traceability matrix must be updated to reflect deprecated requirement IDs.
- Migration notes must accompany the change.
5. Definition of Done
A service implementation is considered done when ALL of the following are true:
| Criterion | Verifier |
|---|---|
All FR, NFR, TR, AR requirements status = Implemented in traceability matrix | Service Lead |
| Unit test coverage meets or exceeds thresholds (domain 90%, app 80%, infra 60%) | QA Lead |
| Integration and contract tests pass in CI | QA Lead |
| E2E tests covering all flows in solution_design.md pass | QA Lead |
| All Grafana dashboards deployed and showing data | Infra Team |
Runbook published in docs/runbooks/<service>.md | Service Lead |
| Secrets configured in Vault / K8s Secrets (not in code) | Security / Infra |
| Kubernetes deployment, HPA, health probes verified | Infra Team |
| OpenAPI spec published and versioned | Service Lead |
All open points in architectural_requirements.md resolved | Platform Architect |
Traceability matrix status updated to Verified | QA Lead |
6. Commit Standards
All commits MUST use Conventional Commits format (AGENT.md §16):
<type>(<scope>): <description>
feat(sms-orchestrator): add retry pipeline with exponential backoff
fix(api-gateway): correct rate limit header parsing
chore(infra): update k8s HPA manifests for smpp-connector
docs(specs): update api-gateway api_design.md with new /v1/sms/status endpoint
Prohibited commit messages: fix stuff, update, misc changes, WIP without elaboration.
7. Spec Review Checklist
Before marking a spec as Approved, the reviewer MUST confirm:
- Document header is complete (version, status, owner, date, references)
- All requirement IDs follow the convention in
_CONVENTIONS.md - Assumptions and open points section is present and populated
- Diagrams render correctly in Mermaid
- Traceability matrix rows reference valid epic/feature/story IDs
- No sensitive data (credentials, PII) present in the document
- Cross-references to other spec files use relative links
8. Tooling
| Tool | Use |
|---|---|
| GitHub PRs | All spec changes reviewed and merged |
| GitHub Actions | CI linting of Markdown (markdownlint) |
| Jira | Epics, features, and user stories from epics.md, features.md, user_stories.md |
| Confluence | Optional publishing target for approved specs |
| ADO | Import via traceability_matrix.csv |
9. Assumptions and Open Points
| ID | Assumption / Open Point | Owner | Resolution Date |
|---|---|---|---|
| A-001 | Jira project key and board structure TBD | Delivery Manager | TBD |
| A-002 | Confluence space for spec publishing TBD | Platform Arch | TBD |
| A-003 | Markdownlint config to be added to .github/ | Platform Eng | TBD |