Skip to content

🛡️ DSOM Guardrail Catalog & Guardrails AI Submission Review Document

Document Purpose: Human Review & Publication Roadmap
Target Audience: Harisfazillah Jamel (LinuxMalaysia), Lead Architects, and Open-Source Community
Ecosystem Target: Guardrails AI PyPI Ecosystem (guardrails-ai-<name>) & DSOM Native Runtime
Status: Draft for Final Review | OKF v0.2 Compliant
Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/DSOM-GUARDRAILS-CATALOG-SUBMISSION-REVIEW/

📌 1. Executive Summary & Hub Transition Note

This document presents the complete catalog of 10 specialized AI Guardrails engineered for the Deep State of Mind (DSOM) protocol. Each guardrail protects a distinct vector of autonomous agent operation, digital sovereignty, token conservation, and GitOps hygiene.

⚠️ Critical Upstream Notice (Guardrails AI Hub Transition):

As documented in the official Guardrails AI architecture updates: * The Centralized Hub Cutoff: Guardrails AI has transitioned away from the centralized guardrails hub install private registry towards standard standalone Python packages on PyPI (guardrails-ai-<validator-name>). * Contribution & Publishing Model: We package our custom validators as open-source PyPI packages using standard Python build tooling (uv build, flit, or hatchling), allowing any developer in the global Guardrails AI community to install them via uv add guardrails-ai-dsom-<validator>.

🗂️ 2. The Complete DSOM 10-Guardrail Inventory

Below is the exhaustive inventory of all guardrails required to guarantee 100% compliance with the DSOM protocol.

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                THE 10 DSOM SOVEREIGN GUARDRAILS                                  │
├────────────────────────────────┬────────────────────────────────┬────────────────────────────────┤
│ 1. OKF Frontmatter & BOM       │ 2. OKF v0.2 Trust Signals      │ 3. Sovereign Signature Footer │
│ 4. Credential & PII Guardian   │ 5. Isolated Python Execution   │ 6. Byte-Capped Terminal Guard │
│ 7. Atomic Commit Gatekeeper    │ 8. Skill Token Window Gate     │ 9. Knowledge-First AST Router │
│ 10. Root Cleanliness Guardian  │                                │                                │
└────────────────────────────────┴────────────────────────────────┴────────────────────────────────┘

1️⃣ Guardrail 1: OKF Frontmatter & UTF-8 BOM Stripper (guardrails-ai-dsom-okf-bom)

  • DSOM Rule Reference: Rule 2 & Rule 25 (Open Knowledge Format & GitHub Web Compatibility).
  • Threat Vector: Windows editors and raw LLM text generation inserting hidden UTF-8 Byte Order Marks (\xef\xbb\xbf) and missing opening YAML frontmatter fences (---), which breaks GitHub web rendering and downstream parser scripts.
  • Validation Logic:
  • Inspects raw string start.
  • If \ufeff is detected, strips it immediately (on_fail="fix").
  • Asserts line 1 starts with ---.
  • Guardrails AI Class: GuardrailsOKFBOMValidator
  • On-Fail Actions: fix (automatically strips BOM and normalizes fence) or fail.
# Prototype Implementation
from guardrails.validators import Validator, register_validator, PassResult, FailResult

@register_validator(name="dsom/okf_bom_validator", data_type="string")
class GuardrailsOKFBOMValidator(Validator):
    def validate(self, value, metadata=None):
        text = str(value)
        if text.startswith("\ufeff"):
            return FailResult(error_message="BOM detected", fix_value=text.lstrip("\ufeff"))
        if not (text.startswith("---\n") or text.startswith("---\r\n")):
            return FailResult(error_message="Document must start on Line 1 with '---'")
        return PassResult()

2️⃣ Guardrail 2: OKF v0.2 Provenance & Trust Signal Gate (guardrails-ai-dsom-okf-trust)

  • DSOM Rule Reference: Rule 6 & Rule 21 (Opportunistic OKF v0.2 Migration & Temporal Verification).
  • Threat Vector: LLMs creating or updating documentation without provenance metadata, leading to unverified hallucinations and stale architectural drift.
  • Validation Logic:
  • Parses YAML frontmatter into a dictionary.
  • If okf_version: 0.2, asserts all 6 trust fields exist: sources (list), generated (string), verified (bool), status (string), stale_after (ISO timestamp), topics (list of 3-5 tags).
  • Guardrails AI Class: GuardrailsOKFTrustValidator
  • On-Fail Actions: reask (prompts LLM to supply missing source links and verification status).

3️⃣ Guardrail 3: Sovereign Signature & Modification Date Auditor (guardrails-ai-dsom-sovereign-signature)

  • DSOM Rule Reference: Rule 13 (Sovereign Signature & Modification Date Mandate).
  • Threat Vector: Agents modifying markdown documents without refreshing the explicit footer signature date, causing human operators and peer agents (Jules/Antigravity) to lose track of document freshness.
  • Validation Logic:
  • Inspects the last 3 lines of markdown text.
  • Verifies presence of the standard DSOM footer: *Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | YYYY-MM-DD*.
  • Verifies that YYYY-MM-DD matches the current session date.
  • Guardrails AI Class: GuardrailsSovereignSignatureValidator
  • On-Fail Actions: fix (automatically appends or updates the date signature) or fail.

4️⃣ Guardrail 4: Defensive Credential & Secret Interceptor (guardrails-ai-dsom-credential-guardian)

  • DSOM Rule Reference: Rule 24 (Defensive Credential Handling Mandate).
  • Threat Vector: Agents or human prompts inadvertently pasting GitHub tokens (ghp_*), GitLab tokens (glpat-*), AWS keys (AKIA*), or SSH/RSA Private Keys into persistent files or chat logs.
  • Validation Logic:
  • Runs high-performance regular expressions across all output text and tool parameters.
  • Blocks execution instantly if an API key or private key pattern is detected.
  • Guardrails AI Class: GuardrailsCredentialGuardian
  • On-Fail Actions: exception / block (refuses to proceed and advises human to rotate keys).

5️⃣ Guardrail 5: Isolated Python Execution & Tool Gatekeeper (guardrails-ai-dsom-uv-gatekeeper)

  • DSOM Rule Reference: Rule 16 (The uv Isolated Execution Mandate).
  • Threat Vector: Agents running unmanaged pip install, python, or python3 commands, polluting system Python and risking PATH hijacking on Windows.
  • Validation Logic:
  • Inspects CLI invocation commands.
  • Intercepts and blocks commands containing pip, python, or python3.
  • Suggests uv run or uv add.
  • Guardrails AI Class: GuardrailsUVExecutionValidator
  • On-Fail Actions: fix (rewrites pip install X to uv add X) or block.

6️⃣ Guardrail 6: Byte-Capped Terminal Output Interceptor (guardrails-ai-dsom-byte-cap)

  • DSOM Rule Reference: Rule 10 (Byte-Capped Executions & Context Window Defense).
  • Threat Vector: Commands returning massive payloads (e.g. cat 50MB.log or verbose build logs) that flood the LLM context window, triggering token budget exhaustion and memory amnesia.
  • Validation Logic:
  • Inspects terminal command outputs or tool string returns.
  • Measures token/byte size.
  • Truncates text exceeding 4,000 bytes and appends a [TRUNCATED BY DSOM BYTE-CAP GUARDRAIL] notice.
  • Guardrails AI Class: GuardrailsByteCapValidator
  • On-Fail Actions: fix (programmatically truncates and preserves context budget).

7️⃣ Guardrail 7: Granular Atomic Git Commit Enforcer (guardrails-ai-dsom-atomic-commit)

  • DSOM Rule Reference: Rule 4 (Git Sovereignty & Atomic Commits).
  • Threat Vector: Agents running blanket git commit -am "update" or staging all unrelated files across the entire repo in one monolithic commit.
  • Validation Logic:
  • Inspects Git commands before execution.
  • Blocks git commit -am or commits with non-semantic messages (e.g., "fixed stuff", "wip").
  • Requires semantic Conventional Commit format (feat(...), docs(...), fix(...), refactor(...)).
  • Guardrails AI Class: GuardrailsAtomicCommitValidator
  • On-Fail Actions: block (instructs agent to stage files logically and write semantic messages).

8️⃣ Guardrail 8: Skill Token Window Gatekeeper (guardrails-ai-dsom-skill-token-gate)

  • DSOM Rule Reference: Rule 19 (Skill Modification Quality Gate & Progressive Disclosure).
  • Threat Vector: AI agents authoring massive SKILL.md documents (>4,000 tokens) that bloat context windows when semantic discovery triggers.
  • Validation Logic:
  • Uses tiktoken (cl100k_base or o200k_base) to measure SKILL.md payload token counts.
  • Blocks any skill exceeding 4,000 tokens.
  • Enforces offloading reference blocks to a references/ subdirectory.
  • Guardrails AI Class: GuardrailsSkillTokenGate
  • On-Fail Actions: block (forces agent to offload detailed tables to references/).

9️⃣ Guardrail 9: Knowledge-First AST Discovery Interceptor (guardrails-ai-dsom-knowledge-first)

  • DSOM Rule Reference: Rule 20 & Rule 21 (Local Knowledge-First Discovery Protocol).
  • Threat Vector: Agents jumping straight to terminal probe commands or external web queries without first checking local OKF documentation and spatial brain state.
  • Validation Logic:
  • Intercepts task initialization.
  • Verifies that the agent has performed grep_search on .agents/brain/ or docs/ before executing system commands.
  • Guardrails AI Class: GuardrailsKnowledgeFirstValidator
  • On-Fail Actions: reask (prompts agent: "You must search local OKF memory first before executing OS commands").

🔟 Guardrail 10: Root Workspace Cleanliness & SaaS Isolation Guard (guardrails-ai-dsom-root-cleanliness)

  • DSOM Rule Reference: Rule 17 (Root Workspace Cleanliness Mandate).
  • Threat Vector: Agents dumping scratch files, temporary logs, or ad-hoc scripts into the repository root instead of .agents/, docs/, or tools/.
  • Validation Logic:
  • Checks target file paths for write operations.
  • Permits only core governance files (README.md, SUMMARY.md, START-HERE.md, llms.txt, .gitignore, ansible.cfg) and SaaS verification files (context7.json).
  • Redirects all other docs to docs/ and tools to tools/.
  • Guardrails AI Class: GuardrailsRootCleanlinessValidator
  • On-Fail Actions: fix (redirects file path to appropriate subdirectory) or block.

📦 3. Packaging & PyPI Publishing Architecture

To distribute these guardrails to the broader AI community and the Guardrails AI ecosystem, we organize them into an open-source mono-package with individual plugin exports:

Package Naming & Layout:

guardrails-ai-dsom/
├── pyproject.toml
├── README.md
├── LICENSE (GPL-3.0 / Apache-2.0 Dual License)
└── src/
    └── guardrails_dsom/
        ├── __init__.py
        ├── okf_bom_validator.py            # Guardrail 1
        ├── okf_trust_validator.py          # Guardrail 2
        ├── sovereign_signature.py          # Guardrail 3
        ├── credential_guardian.py          # Guardrail 4
        ├── uv_gatekeeper.py                # Guardrail 5
        ├── byte_cap_validator.py           # Guardrail 6
        ├── atomic_commit_validator.py      # Guardrail 7
        ├── skill_token_gate.py             # Guardrail 8
        ├── knowledge_first_validator.py    # Guardrail 9
        └── root_cleanliness_validator.py   # Guardrail 10

PyPI Installation:

uv add guardrails-ai-dsom

Universal Usage in Any Guardrails AI Application:

from guardrails import Guard
from guardrails_dsom import (
    GuardrailsOKFBOMValidator,
    GuardrailsCredentialGuardian,
    GuardrailsSovereignSignatureValidator,
)

# Protect an AI Agent with DSOM Sovereign Guardrails
guard = Guard().use_many(
    GuardrailsOKFBOMValidator(on_fail="fix"),
    GuardrailsCredentialGuardian(on_fail="exception"),
    GuardrailsSovereignSignatureValidator(on_fail="fix"),
)

validated_output = guard.validate(llm_generated_content)

📋 4. Next Steps for Human Review & Release

Milestone Action Item Responsible
Review 1 Human Architect (Harisfazillah Jamel) reviews the 10-guardrail list and approves scope. Human
Review 2 Finalize license model (GPL v3.0 core vs. Apache 2.0 PyPI wrapper for Guardrails AI ecosystem). Human
Step 3 Scaffold tools/guardrails-ai-dsom/ package directory with automated unit test suites. AI Twin
Step 4 Build wheel via uv build and publish to PyPI (guardrails-ai-dsom). Human / CI
Step 5 Submit documentation PR / listing to Guardrails AI community showcase. Human

📚 SOURCES

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-22
Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0