Document Identifier: GOVERNANCE.md Version: 1.0.0-draft Status: PROPOSED Authority Level: ROOT Effective Date: Upon acceptance Last Modified: 2026-01-18
This document establishes the governance framework for the SpiritStream project. It defines the authoritative structure, decision-making processes, stakeholder responsibilities, lifecycle management, and sustainability model that govern all project activities.
This document is the Single Source of Truth (SSOT) for the governance domain. All other governance-related documents derive their authority from this specification.
| Stage | Meaning | This Document |
|---|---|---|
| PROPOSED | Under review, not yet binding | Current |
| ACCEPTED | Binding upon all stakeholders | Target |
| AMENDED | Modified via governance process | Future |
The key words "SHALL", "SHALL NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
| Keyword | Requirement Level |
|---|---|
| SHALL / REQUIRED / MUST | Absolute requirement |
| SHALL NOT / MUST NOT | Absolute prohibition |
| SHOULD / RECOMMENDED | Strong recommendation with valid exceptions |
| SHOULD NOT / NOT RECOMMENDED | Strong discouragement with valid exceptions |
| MAY / OPTIONAL | Truly optional |
This document MAY be amended only through the governance process defined herein. Amendments SHALL follow the same lifecycle as any governance proposal.
This specification:
- Establishes Authority - Defines the authoritative hierarchy of project documents
- Defines Process - Specifies how decisions are made and documented
- Assigns Responsibility - Clarifies stakeholder roles and accountabilities
- Manages Lifecycle - Governs features, versions, support, and end-of-life
- Ensures Sustainability - Enables long-term project viability
This specification applies to:
- All project repositories under the SpiritStream organization
- All contributors, maintainers, reviewers, and stakeholders
- All governance documents, processes, and ceremonies
- All versions, branches, and releases
This specification does NOT govern:
- Technical implementation decisions (see
roadmap.md) - Code style and formatting (see
.claude/rules/) - Third-party dependencies and their licenses
- Individual contributor conduct (see
CODE_OF_CONDUCT.md)
This specification is informed by:
- Semantic Versioning 2.0.0
- Conventional Commits
- RFC 2119 - Requirement Levels
- Contributor Covenant
The following documents are indispensable for the application of this specification. For dated references, only the edition cited applies. For undated references, the latest edition applies.
| Document | Authority | Domain |
|---|---|---|
GOVERNANCE.md |
ROOT | This document - governance SSOT |
MILESTONES_CEREMONY.md |
DELEGATED | Process execution |
MILESTONES.main.md |
DELEGATED | Proposal intake |
MILESTONES.latest.md |
DELEGATED | Current commitments |
MILESTONES.v*-*.md |
DELEGATED | Frozen agreements |
CONTRIBUTORS.md |
DELEGATED | Contribution process |
REVIEWERS.md |
DELEGATED | Review process |
CODE_OF_CONDUCT.md |
DELEGATED | Community standards |
roadmap.md |
INFORMATIVE | Technical direction |
┌─────────────────────────────────────────────────────────────────────┐
│ GOVERNANCE.md │
│ (ROOT - This Document) │
│ │
│ - Defines authority hierarchy │
│ - Establishes governance principles │
│ - Cannot be overridden by any other document │
│ - Amendments require explicit governance ceremony │
└─────────────────────────────────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ MILESTONES │ │ CONTRIBUTORS │ │ CODE_OF │
│ _CEREMONY.md │ │ .md │ │ CONDUCT.md │
│ │ │ │ │ │
│ DELEGATED │ │ DELEGATED │ │ DELEGATED │
│ Process │ │ Contribution │ │ Conduct │
└──────────────┘ └──────────────┘ └──────────────┘
│
┌───────┼───────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│main.md │ │latest.md│ │v*-*.md │
│ │ │ │ │ │
│DELEGATED│ │DELEGATED│ │DELEGATED│
│Proposals│ │Living │ │Frozen │
└─────────┘ └─────────┘ └─────────┘
In case of conflict between documents:
GOVERNANCE.md(this document) SHALL prevail over all othersMILESTONES_CEREMONY.mdSHALL prevail over milestone documents- Frozen versions (
v*-*.md) SHALL NOT be modified to resolve conflicts - Conflicts SHALL be documented and resolved in
MILESTONES.main.md
For the purposes of this specification, the following terms and definitions apply.
3.1.1 Governance The framework of rules, practices, and processes by which the project is directed and controlled.
3.1.2 Single Source of Truth (SSOT) An authoritative document that exclusively owns a specific domain. Updates to that domain SHALL occur only in that document.
3.1.3 Ceremony A defined process for making governance decisions, including required participants, inputs, and outputs.
3.1.4 Blocker An explicit impediment preventing a governance item from advancing. Blockers concern AGREEMENT, not implementation.
3.1.5 Version Cut The act of freezing a governance agreement into an immutable record, creating a versioned milestone document.
3.2.1 Living Document A document that evolves continuously until frozen by a version cut.
3.2.2 Frozen Document A document that SHALL NOT be modified except through stage promotion or patch amendments.
3.2.3 Intake Funnel A permanent document that accumulates proposals before they graduate to living documents.
3.3.1 Maintainer An individual with commit access who has accepted responsibility for one or more project domains.
3.3.2 Reviewer An individual authorized to approve or request changes on pull requests.
3.3.3 Contributor Any individual who submits changes, documentation, or feedback to the project.
3.3.4 Sponsor An individual or organization providing financial or resource support to the project.
3.3.5 User Any individual or organization that uses the project software.
3.4.1 Feature Lifecycle The progression of a feature from proposal through implementation, release, maintenance, and retirement.
3.4.2 Version Lifecycle The progression of a version through alpha, beta, stable, and patch stages.
3.4.3 Support Lifecycle The commitment to maintain, patch, and support a version or feature over time.
3.4.4 End-of-Life (EOL) The termination of support for a version or feature, after which no updates will be provided.
3.5.1 Development Branch (main)
The primary branch where development occurs. CI MAY fail on individual commits.
3.5.2 Production Branch (latest)
The upstream branch containing production-ready code. CI SHALL pass on every commit.
3.5.3 Release Branch (v*-*)
A frozen branch representing a specific version release. CI SHALL pass on every commit.
The governance model is founded on four principles:
Development velocity and governance maturity are INDEPENDENT variables.
- Engineering MAY implement speculatively before governance formalizes
- Stakeholders MAY align on direction without blocking development
- Agreement MAY be frozen while implementation continues
- Multiple versions MAY be planned simultaneously
Release artifacts and governance commitment are INDEPENDENT.
- Users SHALL receive patches without waiting for governance approval
- Features MAY be fully developed and experienced before governance commits
- Maintainer/sponsor commitment MAY be the LAST blocker, not the first
- Communities MAY validate features before formal release commitment
The governance model follows eventual consistency principles:
- Proposals accumulate asynchronously
- Acceptance happens when alignment is reached
- Version cuts happen when agreement matures
- Implementation happens when resources permit
There is no REQUIRED ordering between these activities.
All governance decisions MAY be revisited:
- Accepted items MAY be deferred
- Stable versions MAY be patched
- Rejected items MAY be re-proposed
- Mature features MAY be removed before governance commits
Each document SHALL own its domain exclusively:
| Concern | SSOT Document | Owner |
|---|---|---|
| Governance authority | GOVERNANCE.md |
Maintainers |
| Process execution | MILESTONES_CEREMONY.md |
Maintainers |
| Current commitments | MILESTONES.latest.md |
Maintainers |
| Proposals | MILESTONES.main.md |
Community |
| Contribution process | CONTRIBUTORS.md |
Maintainers |
| Review process | REVIEWERS.md |
Reviewers |
| Technical direction | roadmap.md |
Technical leads |
Every governance item SHALL have explicit state:
| State | Meaning | Transitions To |
|---|---|---|
PROPOSED |
Under discussion | ACCEPTED, DEFERRED, REJECTED |
ACCEPTED |
Committed with criteria | COMPLETE, BLOCKED |
BLOCKED |
Has unresolved impediment | ACCEPTED (when resolved) |
COMPLETE |
All criteria met | (terminal) |
DEFERRED |
Moved to future version | PROPOSED (in future) |
REJECTED |
Explicitly removed | PROPOSED (if re-proposed) |
State transitions SHALL be documented with rationale.
The project SHALL maintain the following branch structure:
┌─────────────────────────────────────────────────────────────────────┐
│ main ───────────────────────────────────────────────────────── │
│ │ Development intake │
│ │ CI: NOT required to pass on every commit │
│ │ Aligns with: MILESTONES.main.md │
│ │ │
│ │ auto-promote (when CI passes) │
│ ▼ │
│ latest ─────────────────────────────────────────────────────── │
│ │ Production-ready upstream │
│ │ CI: MUST pass on every commit │
│ │ Aligns with: MILESTONES.latest.md │
│ │ │
│ │ create release branch (when governance ACCEPTS) │
│ ▼ │
│ v<X>.<Y>.<Z>-<stage> ───────────────────────────────────────── │
│ Frozen release branch │
│ CI: MUST pass on every commit │
│ Aligns with: MILESTONES.v<X>.<Y>.<Z>-<stage>.md │
└─────────────────────────────────────────────────────────────────────┘
| Branch | Document | CI Requirement | Artifact Generation |
|---|---|---|---|
main |
MILESTONES.main.md |
MAY fail | None |
latest |
MILESTONES.latest.md |
SHALL pass | Preview/Nightly |
v*-alpha |
MILESTONES.v*-alpha.md |
SHALL pass | Alpha release |
v*-beta |
MILESTONES.v*-beta.md |
SHALL pass | Beta release |
v*-stable |
MILESTONES.v*-stable.md |
SHALL pass | Stable release |
Trigger: All CI checks pass on main
Action: Automatic merge to latest
Human Intervention: None REQUIRED
This ensures users receive patches as soon as CI validates them.
Trigger: Governance ACCEPTS a version (cuts MILESTONES.v*-<stage>.md)
Action: Create branch v*-<stage> from latest
Human Intervention: REQUIRED (maintainer ceremony)
This ensures releases only occur when governance explicitly commits.
This model enables:
- Downstream users don't wait - Patches flow automatically
- Features mature before commitment - Users experience via
latest - Maintainer is LAST blocker - Not first
- Sponsorship model - Features can be 100% ready, awaiting only commitment
- Reversibility - Features can be removed before release
Authority: Highest within project Responsibilities:
- Domain ownership and stewardship
- Governance ceremony execution
- Version cut decisions
- Blocker resolution
- Capacity management
Accountability:
- Response time SLAs (see
REVIEWERS.md) - Domain quality standards
- Mentorship of contributors
Authority: Code review approval Responsibilities:
- Technical review per
REVIEWERS.md - Quality gate enforcement
- Constructive feedback
Accountability:
- Review SLA compliance
- Blocking/non-blocking categorization
- Process adherence
Authority: Proposal submission Responsibilities:
- Follow
CONTRIBUTORS.md - Respond to feedback
- Test changes
Rights:
- Timely review
- Constructive feedback
- Recognition
Authority: Resource provision Responsibilities:
- Financial or resource commitment
- Clear scope definition
- Timeline expectations
Benefits:
- Accelerated governance for sponsored features
- Recognition
- Influence on prioritization
Authority: Feedback provision Responsibilities:
- Issue reporting
- Feature validation via
latest
Rights:
- Access to
latestartifacts - Transparent roadmap
- Security patch access
Domains SHALL have explicit owners:
| Domain | SSOT | Ownership Requirement |
|---|---|---|
| Governance | GOVERNANCE.md |
Maintainer consensus |
| Process | MILESTONES_CEREMONY.md |
Maintainer |
| Commitments | MILESTONES.latest.md |
Maintainer |
| Contribution | CONTRIBUTORS.md |
Maintainer |
| Review | REVIEWERS.md |
Reviewer lead |
| Technical | roadmap.md |
Technical lead |
Ownership changes SHALL follow the claiming process in MILESTONES.latest.md.
| Commitment | Measurement | Target |
|---|---|---|
| PR Response | Time to first review | Per REVIEWERS.md SLA |
| Issue Triage | Time to label/assign | 72 hours |
| Security Response | Time to acknowledge | 24 hours |
| Breaking Changes | Advance notice | 2 weeks minimum |
| Stakeholder | Commitment |
|---|---|
| Contributors | Follow CONTRIBUTORS.md |
| Reviewers | Follow REVIEWERS.md |
| Maintainers | Meet SLAs, maintain domains |
| Sponsors | Honor commitments |
┌─────────────────────────────────────────────────────────────────────┐
│ FEATURE LIFECYCLE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PROPOSAL ──────> IMPLEMENTATION ──────> RELEASE ──────> MAINTENANCE │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ main.md main branch v*-* branch Patches │
│ (governance) (code) (artifacts) (support) │
│ │ │ │ │ │
│ └──────────────────┴───────────────────┴──────────────────┘ │
│ INDEPENDENT TIMELINES │
│ │
│ ▼ │
│ END-OF-LIFE │
└─────────────────────────────────────────────────────────────────────┘
- Feature proposed in
MILESTONES.main.md - Discussion and refinement
- Acceptance into
MILESTONES.latest.md
- Development in
mainbranch - CI validation
- Auto-promotion to
lateston pass
- Governance cuts version
- Release branch created
- Artifacts generated
- Bug fixes and security patches
- Backports to supported versions
- Documentation updates
- Announced in advance (see Section 7.4)
- Final security patch window
- Archive and deprecation
┌─────────────────────────────────────────────────────────────────────┐
│ VERSION LIFECYCLE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ latest.md ────> v<X>-alpha ────> v<X>-beta ────> v<X>-stable │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Living Initial Refined Locked │
│ commitments agreement agreement agreement │
│ │
│ Mutability decreases ────────────────────> │
│ │
│ │ │
│ ▼ │
│ v<X>-patch │
│ Append-only │
└─────────────────────────────────────────────────────────────────────┘
- Initial agreement formalized
- Open to significant changes
- Early adopter testing
- Agreement refined from feedback
- Open to minor changes only
- Wider testing
- Agreement locked
- No changes except patches
- General availability
- Append-only amendments
- Critical fixes only
- Maintains stability
| Tier | Duration | Coverage |
|---|---|---|
| Active | Current + 1 prior | All fixes |
| Security | Current + 2 prior | Security only |
| Extended | Sponsored | Per agreement |
| EOL | None | No support |
Version Timeline:
v1.0 ──────> v1.1 ──────> v2.0 ──────> v2.1 ──────> v3.0
│ │ │ │
▼ ▼ ▼ ▼
EOL when EOL when EOL when Current
v2.0+2 v3.0+2 v3.0 stable
Support at v3.0 release:
- v3.0: Active (all fixes)
- v2.1: Active (all fixes)
- v2.0: Security (security only)
- v1.x: EOL (no support)
- SHALL be announced minimum 3 months before EOL
- SHALL be documented in release notes
- SHOULD include migration guidance
- 30 days after EOL for final security patches
- Critical vulnerabilities only
- No new features or non-security fixes
EOL MAY be extended via sponsorship (see Section 8.3).
The project SHALL maintain sustainability through:
- Bounded Scope - Capacity limits scope, not inverse
- Explicit Capacity - Published in
MILESTONES.latest.md - Sponsor Enablement - Clear path for resource provision
- Recognition - Contributors and sponsors acknowledged
| Type | Scope | Benefit |
|---|---|---|
| Feature | Specific feature | Accelerated governance |
| Maintenance | Ongoing support | Extended EOL |
| Security | Security patches | Priority response |
| General | Project health | Recognition, influence |
- Proposal: Sponsor contacts maintainers
- Scoping: Mutual agreement on deliverables
- Commitment: Formalized in governance
- Delivery: Per agreed timeline
- Recognition: Per sponsor preferences
Sponsorship enables the "maintainer as final blocker" pattern:
Feature State:
✓ Fully implemented in latest
✓ CI passes
✓ Users validated via preview artifacts
✓ Community enthusiasm high
⊘ BLOCKER: No maintainer committed
Resolution via sponsorship:
1. Sponsor commits resources
2. Maintainer accepts commitment
3. Blocker resolved
4. Version cut proceeds
Versions MAY receive extended support when:
- Sponsor commits to maintenance costs
- Maintainer capacity available
- Security patch feasibility confirmed
| Term | Requirement |
|---|---|
| Duration | Minimum 6 months |
| Scope | Security patches only |
| Response | Per standard SLA |
| Cost | Sponsor-maintainer agreement |
Features MAY be bounty-eligible when:
- Feature is fully specified in
MILESTONES.latest.md - Feature is blocked only on maintainer commitment
- Bounty is sufficient to fund maintenance
- Feature identified as bounty-eligible
- Bounty posted by sponsor or community
- Maintainer claims bounty and commitment
- Feature graduates to release
- Bounty disbursed per agreement
This specification (GOVERNANCE.md) is itself governed by the governance process:
- Proposals via
MILESTONES.main.mdwith category "Governance" - Acceptance requires maintainer consensus
- Versioning follows semantic versioning
- Backward Compatibility with existing milestone documents
┌─────────────────────────────────────────────────────────────────────┐
│ AMENDMENT PROCESS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. PROPOSAL │
│ └── Add to MILESTONES.main.md with category "Governance" │
│ │
│ 2. DISCUSSION │
│ └── Open period for stakeholder feedback │
│ │
│ 3. CONSENSUS │
│ └── Maintainer consensus required │
│ └── No dissenting maintainer after discussion period │
│ │
│ 4. ACCEPTANCE │
│ └── Move to MILESTONES.latest.md │
│ │
│ 5. INTEGRATION │
│ └── Update GOVERNANCE.md │
│ └── Increment version │
│ │
│ 6. ANNOUNCEMENT │
│ └── Notify stakeholders │
└─────────────────────────────────────────────────────────────────────┘
| Type | Version Impact | Approval |
|---|---|---|
| Clarification | Patch | Single maintainer |
| Minor change | Minor | Maintainer majority |
| Major change | Major | Maintainer consensus |
| Principle change | Major | All maintainers + community input |
Amendments SHALL:
- NOT invalidate existing frozen milestone documents
- NOT retroactively change historical decisions
- Provide transition guidance when needed
- Maintain document relationship integrity
- Proposals flow through main → latest regularly
- Blockers have owners and progress
- Version cuts occur when agreement matures
- Documents stay synchronized
- Branches align with documents
- Artifacts enable early validation
- Sponsors/maintainers emerge from community
- Proposals stagnate in
main.md - Blockers without owners or progress
latest.mdgrows unboundedly- No version cuts despite mature agreement
- Documents contradict each other
latestbranch diverges fromlatest.md- No users validating
latestartifacts
| Audit | Frequency | Owner |
|---|---|---|
| Document sync | Monthly | Maintainers |
| Branch alignment | Per release | CI/CD |
| Blocker review | Weekly | Maintainers |
| Capacity check | Quarterly | Maintainers |
- All documents reference correct versions
- No conflicting statements between documents
- All blockers have owners
- All domains have owners
- Branch CI status matches requirements
- Artifacts generated for appropriate branches
| Finding | Action |
|---|---|
| Stagnant proposals | Schedule proposal review ceremony |
| Stuck blockers | Escalate or defer |
Unbounded latest.md |
Cut version or prune scope |
| No version cuts | Lower bar for alpha cut |
| Document drift | Reconciliation audit |
| Branch drift | Align branches with documents |
| No validation | Promote latest artifacts |
| Document | One-Line Purpose |
|---|---|
GOVERNANCE.md |
Governance SSOT - you are here |
MILESTONES_CEREMONY.md |
How governance process works |
MILESTONES.main.md |
Ideas under discussion |
MILESTONES.latest.md |
Current commitments |
MILESTONES.v*-*.md |
Frozen agreement records |
CONTRIBUTORS.md |
How to contribute |
REVIEWERS.md |
How to review |
CODE_OF_CONDUCT.md |
Community standards |
roadmap.md |
Technical direction |
- Agreement and implementation are DECOUPLED
- Implementation and release are DECOUPLED
- Version cuts are about AGREEMENT maturity
- Blockers are about ALIGNMENT, not implementation
- Documents reference PATTERNS, not specific versions
- Branches ALIGN with governance documents
- Every state is EXPLICIT
- Maintainer/sponsor commitment MAY be final blocker
| I want to... | Do this... |
|---|---|
| Propose a governance change | Add to MILESTONES.main.md |
| See current commitments | Read MILESTONES.latest.md |
| Understand the process | Read MILESTONES_CEREMONY.md |
| Contribute code | Read CONTRIBUTORS.md |
| Review code | Read REVIEWERS.md |
| Get early access | Use latest branch artifacts |
| Get stable release | Use release branch artifacts |
| Sponsor a feature | Contact maintainers |
| Extend support | Contact maintainers |
| Keyword | Meaning |
|---|---|
| SHALL | Absolute requirement |
| SHALL NOT | Absolute prohibition |
| SHOULD | Recommendation |
| SHOULD NOT | Discouragement |
| MAY | Optional |
See MILESTONES.main.md for proposal template.
See MILESTONES_CEREMONY.md for ceremony procedures.
See REVIEWERS.md for review checklists.
| Version | Date | Change | Author |
|---|---|---|---|
| 1.0.0-draft | 2026-01-18 | Initial specification | @usrbinkat |
This specification requires acceptance per Section 9.2.
| Role | Name | Date | Status |
|---|---|---|---|
| Maintainer | @usrbinkat | TBD | Pending |
This is the root governance document. All governance authority derives from this specification.