Policy as Code: Writing Governance Rules That Execute
Your governance policy is a 47-page PDF that nobody has read since the last audit. Turn it into executable YAML that runs on every pull request with real HIPAA and SOC 2 examples.
Your governance policy is a 47-page PDF that nobody has read since the last audit. Mine is a YAML file that executes on every pull request. Only one of these can tell you, right now, whether your last code change violated a compliance requirement.
I spent years in organizations where policy documents lived in SharePoint and enforcement lived in people’s heads. The gap between what the policy said and what actually happened was invisible until an auditor found it. GuardSpine closes that gap by turning policies into code that runs automatically.
What Policy as Code Actually Means
Policy as code is not a metaphor. It means your governance rules are machine-readable, version-controlled, testable, and executable. They live in the same repository as your application code. They go through the same review process. They have the same audit trail.
A traditional policy statement looks like this:
“All changes to authentication logic must be reviewed by a senior engineer before deployment.”
A policy-as-code equivalent looks like this:
policies:
- name: auth-change-requires-senior-review
description: Changes to authentication logic require L3+ review
trigger:
paths:
- "src/auth/**"
- "src/middleware/auth*"
- "lib/session/**"
content_patterns:
- "password"
- "token"
- "jwt"
- "oauth"
risk_tier: L3
actions:
- type: escalate
to: human
role: senior_engineer
- type: evidence
require: rationale
Both express the same intent. The YAML version executes. When a PR touches files under src/auth/, GuardSpine classifies it as L3, blocks auto-approval, requires a senior engineer to sign off, and records the rationale in the evidence bundle. The PDF version requires someone to remember the rule, notice that the PR touches auth code, and manually enforce the policy.
The Rubric System
GuardSpine’s policy engine is built around rubrics — named sets of rules that map to specific compliance frameworks or organizational standards. A rubric is a YAML file that defines:
Triggers. What conditions activate the rule. File paths, content patterns, change types (new file, deleted file, modified function signature), dependency changes, and configuration changes.
Risk tier. The L0 through L4 classification that determines how the review is routed. L0-L1 auto-approve. L2 gets AI review with comments. L3-L4 require human sign-off.
Actions. What happens when the rule fires. Escalate to human, require specific evidence types, add reviewers, block merge, post a warning, or log for audit.
Evidence requirements. What must be captured in the evidence bundle when this rule fires. Some rules require a rationale. Others require a specific approval role. Others just need a record that the rule was evaluated.
Rubrics compose. You can stack multiple rubrics on a single repository. A healthcare company might run the HIPAA rubric and the SOC 2 rubric simultaneously. If a change triggers rules from both, the most restrictive actions apply.
HIPAA in Practice
Here is a real rubric rule from the HIPAA pack:
- name: phi-access-pattern-change
description: Changes to Protected Health Information access patterns
trigger:
paths:
- "src/models/patient*"
- "src/services/medical*"
- "src/api/health*"
content_patterns:
- "medical_record"
- "diagnosis"
- "treatment"
- "patient_id"
- "date_of_birth"
risk_tier: L4
actions:
- type: escalate
to: human
role: hipaa_officer
- type: evidence
require: [rationale, approval, policy-eval]
- type: pii_shield
mode: strict
patterns: [ssn, medical_record_number, date_of_birth]
When a developer modifies a function that queries patient records, this rule fires. The change is classified as L4 — the highest risk tier. It gets escalated to whoever holds the hipaa_officer role. Auto-approval is impossible. PII-Shield runs in strict mode on the diff, checking for PHI patterns. The evidence bundle must contain a rationale for the change, an explicit approval, and a record of which policy rules were evaluated.
The HIPAA officer does not need to remember to check this. The system enforces it. If they try to merge without the required review, the merge is blocked.
SOC 2 Type II: Continuous Evidence
SOC 2 Type II is different from Type I in a way that matters enormously for policy as code. Type I asks: “Do you have controls?” Type II asks: “Did those controls operate effectively over a period of time?”
Traditional SOC 2 Type II evidence is painful. You collect screenshots, export logs, compile spreadsheets, and pray nothing fell through the cracks during the audit window. Policy as code flips this. Because every policy evaluation is recorded in an evidence bundle, you have continuous proof that controls operated on every change during the entire audit period.
SOC 2 rubric rules cover change management, access control, and risk assessment. Here is a change management rule:
- name: change-management-evidence
description: All production changes must be reviewed and approved
trigger:
branches:
- "main"
- "production"
- "release/*"
risk_tier: L2
actions:
- type: evidence
require: [diff, council-vote, approval]
- type: audit_log
fields: [change_id, reviewer, timestamp, decision, risk_tier]
Every merge to main produces an evidence bundle with the diff, the AI council’s review, and the approval decision. When your SOC 2 auditor asks “show me evidence that all changes to production were reviewed during Q1,” you export the evidence bundles for Q1 merges to main. Done.
No spreadsheet. No screenshots. No “let me check if someone forgot to document that hotfix from February.”
Version Control for Policies
One benefit of policies as code that people overlook: your policies have a commit history.
When the HIPAA officer decides that PHI access patterns should also include insurance_id as a trigger, they open a PR that adds the pattern to the rubric. That PR gets reviewed, approved, and merged. The commit history shows exactly when the policy changed, who changed it, and why.
Compare this to editing a PDF. Who changed paragraph 4.3.2? When? Was it reviewed? Did anyone approve it? The document metadata might tell you when it was last saved. It will not tell you what changed or whether the change was authorized.
Policy version control also means you can answer audit questions like: “What was your PII detection policy on March 15?” Check out the rubric file at that commit hash. The answer is exact, not approximate.
Writing Your First Policy
If you are starting from scratch, begin with three rules:
Rule 1: Classify your critical paths. Identify the file paths and patterns that represent your highest-risk code. Authentication, authorization, payment processing, PII handling, infrastructure configuration. Write trigger rules for those paths and set them to L3 or L4.
Rule 2: Require evidence on production merges. Any merge to your production branch should produce an evidence bundle with at minimum the diff, one review, and an approval record.
Rule 3: Run PII-Shield on everything. Enable PII-Shield with default settings. Whitelist your known high-entropy fields. Let the entropy detector find what your pattern matcher misses.
These three rules cover 80% of what auditors ask about. You can add more specific rules as your compliance requirements become clearer.
The Executable Policy Advantage
The fundamental advantage of policy as code is feedback speed. A PDF policy fails silently — you only discover non-compliance during an audit. An executable policy fails loudly, on the PR that violated it, with a specific explanation of which rule fired and why.
The EU AI Act enforcement date is August 2, 2026. When regulators ask how your AI-assisted changes are governed, “we have a PDF” is not an answer. Executable policy that generates evidence on every change is.
This changes the economics of compliance. Instead of hiring people to manually check whether policy was followed, you hire people to write better policies. The checking is automated. The humans focus on judgment calls — the L3 and L4 escalations that require domain expertise.
Policies should be code because code is testable, versionable, composable, and enforceable. PDFs are none of those things.
GuardSpine ships with rubric packs for HIPAA, SOC 2, and PCI DSS. Bring your compliance requirements and I will show you the policies running on a live repo. Book a walkthrough.