feat: pai-governance-guard — structural authority separation pack

[devongenerally-png]

Summary

pai-governance-guard adds a deterministic governance layer that complements SecurityValidator by addressing a different class of risk: actions that aren't pattern-matchable as dangerous but exceed authorized scope.

SecurityValidator catches known-dangerous commands (rm -rf, credential access, destructive git ops). Governance-guard addresses the structural question: should this action happen at all, given the user's policy?

Repo: https://github.com/MetaCortex-Dynamics/governance-guard

---

The Gap This Fills

PAI's current security model is defense-in-depth with two layers:

1. Pre-commit validation (validate-protected.ts) — scans for credential patterns before commits
2. Runtime validation (SecurityValidator.hook.ts) — pattern-matches commands against patterns.yaml tiers

Both layers are valuable and this pack doesn't replace either of them. But both operate on the same principle: known-bad pattern detection. They block things that look dangerous.

The gap is actions that don't look dangerous but aren't authorized:

• Creating accounts on external services
• Sending API requests to third-party services the user never approved
• Writing to directories outside the project scope
• Invoking tools with side effects the user didn't request

These actions don't match any regex tier. They pass SecurityValidator cleanly. But they exceed the user's intended authorization. The agent proposed the action, evaluated whether it was appropriate, and executed it — all in the same computational pathway.

PAI Principle #5 says: "AI is probabilistic; your infrastructure shouldn't be." Governance-guard makes the authorization decision deterministic.

---

How It Works

Three-phase pipeline as a PreToolUse hook:

Tool Call → PROPOSE → DECIDE → PROMOTE → Execution
               │          │         │
           serialize   evaluate   gate
           + hash      against    on
           intent      policy     verdict
                       (no LLM)

PROPOSE — Serializes the tool call into a structured ActionIntent (tool name, action type, target, parameters). Binds with SHA-256 hash.

DECIDE — Evaluates the intent against a user-defined YAML policy. Pure function. No LLM. No interpretation. Policy + intent → verdict (approve / deny / escalate). Default: deny.

PROMOTE — Approved actions proceed. Denied actions are blocked (exit code 2). Escalated actions prompt the user. Every decision is recorded in a hash-chained witness log.

---

How It Integrates With PAI

This pack is designed as a companion to SecurityValidator, not a replacement:

Layer	What It Catches	Mechanism
validate-protected.ts	Credential leaks in commits	Pattern matching on file content
SecurityValidator.hook.ts	Known-dangerous commands	Regex tiers on bash commands
governance-guard	Unauthorized-but-not-dangerous actions	Deterministic policy evaluation on structured intent

Hook registration: PreToolUse with * matcher (evaluates all tool calls, not just Bash). Runs alongside SecurityValidator — both hooks fire, both must pass.

Policy presets: Three YAML presets that match PAI's security philosophy:

• minimal.yaml — Blocks destructive + credential access (similar scope to SecurityValidator, structured format)
• standard.yaml — Deny-default with explicit allows (recommended)
• strict.yaml — Allow reads only, deny everything else

Witness chain: JSONL log at $PAI_DIR/MEMORY/GOVERNANCE/ — integrates with PAI's existing MEMORY system. Every governance decision is captured as a learning signal, consistent with PAI's continuous learning architecture.

Zero dependencies. Custom YAML parser, Node built-in crypto. Matches PAI's principle of deterministic infrastructure.

---

What's In the Pack

Packs/pai-governance-guard/
├── README.md                    # Pack documentation
├── INSTALL.md                   # AI-assisted installation wizard
├── VERIFY.md                    # Verification checklist
├── src/
│   ├── hooks/
│   │   └── GovernanceGuard.hook.ts   # PreToolUse hook
│   ├── governance/
│   │   ├── types.ts                  # Type definitions
│   │   ├── canonical.ts             # Deterministic hashing (JCS + SHA-256)
│   │   ├── intent.ts                # PROPOSE: ActionIntent serialization
│   │   ├── policy-engine.ts         # DECIDE: Deterministic evaluation
│   │   ├── witness.ts               # PROMOTE: Hash-chained audit log
│   │   └── yaml-parse.ts            # Zero-dep YAML parser
│   └── config/
│       └── settings-fragment.json   # Hook registration config
├── policies/
│   ├── minimal.yaml
│   ├── standard.yaml
│   └── strict.yaml
├── references/
│   └── policy-schema.md            # Policy file format docs
└── tests/
    ├── canonical.test.ts
    ├── yaml-parse.test.ts
    ├── intent.test.ts
    ├── policy-engine.test.ts
    ├── witness.test.ts
    ├── integration.test.ts
    └── adversarial.test.ts

Tests

146 tests passing across 7 test suites:

• canonical.test.ts — Hash computation, deterministic serialization
• yaml-parse.test.ts — YAML parser, all policy presets
• intent.test.ts — Action classification for all tool types
• policy-engine.test.ts — Rule matching, modal gates, policy loading
• witness.test.ts — Hash chain integrity, tamper detection
• integration.test.ts — End-to-end pipeline with all policy presets
• adversarial.test.ts — Spoofed hashes, path traversal, replay attacks, malformed YAML

---

Alignment With PAI Principles

PAI Principle	How governance-guard implements it
#5: Deterministic Infrastructure	Decision layer is a pure function — same policy + same intent = same verdict, every time
#7: Spec / Test / Evals First	146 tests including adversarial coverage, written before implementation
#8: UNIX Philosophy	Does one thing (authorization decisions), composes with existing security layers
#9: ENG / SRE Principles	Hash-chained witness log enables incident reconstruction and compliance auditing
#4: Scaffolding > Model	Authorization decisions removed from the LLM entirely — structural, not behavioral

---

What This Does NOT Do

• Does not replace SecurityValidator (complementary, not competitive)
• Does not verify LLM intent accuracy (fundamental limitation of wrapping an untrusted component)
• Does not perform semantic consequence analysis (evaluates structural properties against policy rules)
• Witness chain is tamper-evident, not tamper-proof (filesystem deletion is detectable but not preventable)

---

About

Built by MetaCortex Dynamics — governance infrastructure for autonomous systems.

The core implementation is also available as a standalone package.

AI disclosure: Architecture review and spec drafting assisted by Claude. All code reviewed, understood, and tested by the author. The PROPOSE/DECIDE/PROMOTE governance architecture is original work. 146/146 tests fully passing.

License: MIT

[danielmiessler]

Hey @devongenerally-png — Kai here, Daniel's AI assistant, doing the next pass of triage on the PAI repo.

Closing this out because the Packs/ distribution model has been removed in v5.0.0 — skills now ship directly under skills/ and pack-install isn't a concept anymore. Governance/authority separation could be valid as a v5 design conversation but not as a Pack.

If you'd like to re-propose this as a v5-native skill or design pattern, please open a fresh issue or PR against the new release. Thanks for taking the time to put this together — really appreciated.

— Kai 🤖