governance.md

Governance System

How policy traceability works for ways. This is the reference layer — for getting started, see governance/README.md. For adding provenance to a way, see provenance.md.

The Compilation Chain

Ways are compiled policy. A human reads a policy document, interprets it for the agent context, and writes a way file — compressed, directive, stripped of rationale. The governance system makes that compilation traceable.

Regulatory Framework    (NIST, ISO, OWASP, SOC 2, CIS, IEEE...)
       ↓
Control Requirement     (NIST SP 800-53 CM-3, OWASP A03:Injection...)
       ↓
Policy Document         (governance/policies/*.md — human prose)
       ↓
Way File                (hooks/ways/*/{name}.md — compiled guidance)
       ↓
Agent Context           (injected at runtime when triggers match)

Each layer compresses the one above it. The regulatory framework is hundreds of pages. The control is a paragraph. The policy is a few pages. The way is 30 lines. The agent sees only the directives — but the full chain is walkable.

Provenance Metadata

Ways carry optional provenance: blocks in their YAML frontmatter:

---
pattern: commit|push
provenance:
  policy:
    - uri: governance/policies/code-lifecycle.md
      type: governance-doc
  controls:
    - id: NIST SP 800-53 CM-3 (Configuration Change Control)
      justifications:
        - Conventional commit types classify changes by nature
        - Atomic commits make each change independently reviewable
    - id: SOC 2 CC8.1 (Change Management)
      justifications:
        - Type prefix and scope create structured change records
  verified: 2026-02-05
  rationale: >
    Conventional commits create structured change records with type
    classification and justification.
---

The runtime strips all frontmatter before injection. Provenance metadata never reaches the agent's context window. Zero tokens. Zero latency. It exists purely for governance — the debug symbols of compiled policy.

Fields

Field	Purpose
policy[].uri	Source policy document — relative path or github://org/repo/path
policy[].type	Classification: adr, governance-doc, regulatory-framework, control-spec
controls[].id	Regulatory control this way addresses
controls[].justifications[]	Specific claims about how guidance satisfies the control
verified	Date provenance was last confirmed accurate
rationale	How policy intent became way guidance — the compilation commentary

Data Flow

flowchart LR
    classDef tool fill:#2196F3,stroke:#1565C0,color:#fff
    classDef data fill:#FF9800,stroke:#E65100,color:#fff
    classDef output fill:#4CAF50,stroke:#2E7D32,color:#fff

    W["way files<br/>(provenance frontmatter)"]:::data
    P["governance/policies/<br/>(policy source docs)"]:::data
    CLI["ways governance"]:::tool
    R["Reports<br/>(coverage, traces,<br/>matrices, lint)"]:::output

    W --> CLI
    P --> CLI
    CLI --> R

Loading

Tools

All governance queries are handled by the ways CLI (ways governance <mode>). The CLI scans way files directly, generates the provenance manifest in memory, and runs queries against it.

Mode	Command	Output
Coverage	ways governance report	Which ways have provenance, which don't
Trace	ways governance trace softwaredev/commits	End-to-end chain for one way
Control query	ways governance control OWASP	Which ways implement a control
Policy query	ways governance policy code-lifecycle	Which ways derive from a policy
Gaps	ways governance gaps	Ways without provenance
Stale	ways governance stale 90	Ways with old verified dates
Active	ways governance active	Cross-reference with way firing stats
Matrix	ways governance matrix	Flat spreadsheet: way / control / justification
Lint	ways governance lint	Validate provenance integrity

All modes support --json for machine-readable output.

Policy Source Documents

Policy documents live in governance/policies/. These are the human-readable interpretation layer — they explain why a way exists, what principle it implements, what the boundaries are. They're the "source code" that ways compile from.

The governance scanner validates that every policy.uri in way frontmatter points to a real file. The provenance chain breaks if policies are moved without updating URIs.

The Growth Pattern

Governance is optional and additive. Most users never need it. The progression:

1. Ways — encode how you do things. Everyone starts here.
2. Policies — write down why. Emerges when ways need rationale or when new team members ask "why do we do it this way?"
3. Provenance — link ways to policies and controls. Emerges when compliance asks "can you prove your agents follow policy?"
4. Reporting — run the governance operator. Emerges when auditors need evidence.

Each step builds on the previous without requiring it. A way without provenance works exactly the same at runtime. Provenance without reporting still documents intent. The system doesn't penalize partial adoption.

Cross-Repo Pattern

In an enterprise, policy documents and way implementations typically live in separate repositories:

compliance-repo/              your-claude-config/
├── docs/architecture/        ├── hooks/ways/
│   ├── ADR-150.md           │   ├── softwaredev/delivery/commits/commits.md
│   └── ADR-200.md           │   │   (provenance: → ADR-150)
├── audit-ledger.json        │   └── softwaredev/code/security/security.md
└── controls.xlsx            └── governance/
                                 ├── policies/
                                 └── provenance-manifest.json

The provenance frontmatter references policies by URI. The manifest bridges repos at verification time. The verify script supports --ledger for cross-referencing external control inventories.

Analogy

Concept	Software Build	Governance System
Source code	.c files	governance/policies/*.md
Compiler	gcc	Human authoring process
Object code	.o files	hooks/ways/*/{name}.md
Debug symbols	DWARF / PDB	provenance: frontmatter block
Symbol table	.map file	provenance-manifest.json
Build system	make	ways governance