Skip to content

GOVERNANCE.md

Latest commit

 

History

History
159 lines (102 loc) · 4.26 KB

GOVERNANCE.md

File metadata and controls

159 lines (102 loc) · 4.26 KB

Gov-Mesh Governance Charter

Project: governance_engine — Core Governance Scanner & Policy Layer

1. Purpose

This repository implements the core governance scanner used across projects. It is responsible for:

  • Scanning codebases for governance and secret-related issues.
  • Applying project-specific governance policy as code.
  • Producing machine-readable reports and governance timelines.

This project is part of the broader Gov-Mesh and may be embedded in other systems (e.g. Omnipath, Syntara, MCP Node) as a reusable engine.

2. Scope

This charter applies to:

  • Source code under the governance_engine/ package.
  • Supporting configuration: pyproject.toml, .govmesh.yml, CI workflows.
  • Documentation in docs/ and GOVERNANCE.md (this file).

It does not cover downstream consumers (other repos) except where they are scanned by this engine.

3. Ownership & Responsibilities

  • Maintainer: inmoa (primary)
  • Module: governance_engine

Responsibilities:

  • Keep the engine installable and usable as a standalone package.
  • Maintain stable CLI behavior for the gov command.
  • Avoid breaking changes without bumping the package version.
  • Ensure secret-scanning defaults are conservative but useful.

4. Change Management

All non-trivial changes should:

  1. Be applied via a branch or clearly isolated commit.
  2. Include:
    • Code changes.
    • Any necessary updates to policy (.govmesh.yml) and docs.
  3. Run the following checks locally before tagging a release:
    • pip install -e .
    • gov --project .
    • gov --project <at least one downstream project>

Versioning rules:

  • PATCH: Internal bugfixes, rule improvements, policy tweaks.
  • MINOR: New rules, new policy fields, new CLI subcommands.
  • MAJOR: Breaking changes to report schema or CLI behavior.

5. Governance Checks & Tooling

The following tools are considered part of the governance surface:

  • gov — this engine’s CLI.
  • snapshot — external snapshot engine used to map project structure.
  • Any CI workflows that:
    • Run gov --project .
    • Archive docs/governance_reports/

Expected outputs:

  • docs/governance_reports/report_<timestamp>.json
  • docs/governance_reports/latest.json
  • docs/governance_reports/timeline.json

These outputs are part of the audit trail and SHOULD be kept under version control or archived by CI where appropriate.

6. Secrets & Sensitive Data

This repository MUST NOT contain:

  • Hard-coded API keys, tokens, or credentials.
  • Private keys or certificate material.
  • Production database URLs or passwords.

Secret detection is handled by:

  • Built-in patterns in GovernancePolicy.
  • Any additional patterns specified in .govmesh.yml.

When a secret is discovered:

  1. Rotate the key upstream (cloud provider, service, etc.).
  2. Remove or mask it from the repository history if necessary.
  3. Add or refine patterns in .govmesh.yml so similar issues are caught early.

7. Policy as Code

Project-specific governance policy is stored in .govmesh.yml at the repo root. This file controls:

  • Extra directories and files to ignore.
  • File extensions to include.
  • File size limits.
  • Additional secret patterns.

Changes to .govmesh.yml are considered governance changes and MUST be reviewed with the same care as code changes.

8. Audit Trail & Timeline

The engine maintains a governance timeline in:

  • docs/governance_reports/timeline.json

This timeline tracks:

  • Total findings over time.
  • Categories of findings (e.g. governance, secrets, internal).
  • Drift between runs (improvement, regression, or no change).

When preparing for audits or external review:

  • Use the latest report + timeline to demonstrate how governance posture evolved over time.
  • Document any intentional exceptions or temporary waivers in commit messages or additional markdown under docs/.

9. Deviation & Exceptions

Any deliberate deviation from this charter MUST be:

  • Documented in a commit message and/or docs/ note.
  • Justified with a clear reason and planned sunset date (if applicable).

Unintentional deviations (e.g. a missed check, forgotten GOV file) should be treated as findings and fixed via normal change management.

Last updated by inmoa via Gov-Mesh engine bootstrap.