agentguard-governance 0.7.0__tar.gz

agentguard_governance-0.7.0/.env.example

@@ -0,0 +1,21 @@
+# AgentGuard AI Review Configuration
+# Copy to .env and fill in your values
+# NEVER commit .env to version control
+
+# Provider: anthropic | openai | anysphere | openai-compatible
+AGENTGUARD_AI_PROVIDER=anthropic
+
+# API key for the selected provider
+AGENTGUARD_AI_API_KEY=your-api-key-here
+
+# Base URL (only for openai-compatible providers)
+# AGENTGUARD_AI_BASE_URL=https://your-api-endpoint/v1
+
+# Model override (optional — provider default used if not set)
+# AGENTGUARD_AI_MODEL=claude-haiku-4-5-20251001
+
+# Mission concretization uses a more capable model for schema reliability
+# Anthropic: claude-sonnet-4-20250514 (instead of haiku)
+# OpenAI: gpt-4o (instead of gpt-4o-mini)
+# Override with AGENTGUARD_MISSION_MODEL=your-model if needed
+# AGENTGUARD_MISSION_MODEL=claude-opus-4-20250514

agentguard_governance-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check agentguard tests
+
+      - name: Run tests
+        run: pytest --tb=short
+
+      - name: Test web (with optional web deps)
+        run: |
+          pip install -e ".[web]"
+          pytest tests/test_web_server.py --tb=short
+
+      - name: Build package
+        run: pip install build hatchling && python -m build --no-isolation

agentguard_governance-0.7.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: pip install build hatchling
+
+      - name: Build package
+        run: python -m build --no-isolation
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

agentguard_governance-0.7.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.env
+.venv
+venv/
+env/
+.pytest_cache/
+.ruff_cache/
+*.log
+report.md
+agentguard-overrides.log
+.DS_Store
+web/node_modules/
+web/dist/

agentguard_governance-0.7.0/.trace_sync

@@ -0,0 +1 @@
+c2f27bd

agentguard_governance-0.7.0/AI_CONTEXT.md

@@ -0,0 +1,132 @@
+# AI_CONTEXT.md
+
+> Keep this file current. Update after each significant session.
+
+---
+
+## Project
+
+**Name:** AgentGuard  
+**Version:** 0.7.0  
+**Repo:** github.com/MyPatric69/agentguard  
+**Purpose:** Governance layer for autonomous AI agents — pre-flight
+checks, runtime enforcement, concretization, and audit trail.
+
+**Positioning:** Not an observability tool. The governance layer that
+runs before, during, and after observability tools do.
+
+**Taglines:**
+- "Maximum instruction, minimum interpretation."
+- "It doesn't eliminate the probability of failure. It reduces the impact."
+
+## Stack
+
+- Python 3.11+
+- Click (CLI), Rich (output), PyYAML (config), python-dotenv (env)
+- Optional AI: Anthropic SDK, OpenAI SDK
+- Optional Web: FastAPI + uvicorn, React 18 + Vite 5, xterm.js
+- Build: hatchling, PyPI: agentguard-governance
+
+## Current State (v0.7.0)
+
+### CLI Commands (12 total)
+- `agentguard check` — pre-flight: governance + prompt + harness checks
+- `agentguard check --ai-review` — + AI scope quality score 1-10
+- `agentguard init --interactive` — basic setup, no AI required
+- `agentguard init --guided` — AI-concretized 5-step governance dialog
+- `agentguard enforce` — PreToolUse hook, exit 0/2, deterministic
+- `agentguard watch` — native Claude Code JSONL monitoring
+- `agentguard report` — post-session Markdown governance report
+- `agentguard review` — interactive governance update cycle
+- `agentguard review --guided` — AI-assisted field update
+- `agentguard verify` — prompt-pin drift detection
+- `agentguard override` — documented exception with mandatory reason
+- `agentguard web` — browser UI (requires pip install agentguard-governance[web])
+
+### Web UI (v0.7.0)
+Six tabs: Pre-Flight Check, Governance, Verify Pins, Terminal,
+Setup Governance, Review & Update.
+
+Key features:
+- Governance Score Ring on Check panel
+- Color-coded scope sections (green/red/amber)
+- xterm.js terminal with WebSocket PTY — runs interactive commands
+- Quick Commands bar in terminal
+- Run in Terminal buttons in Setup/Review panels
+- Multi-project switcher (--path flag, dropdown when >1 project)
+- Project name shown in header with check status
+
+### Key Technical Decisions
+- Enforcement: deterministic, no LLM, never probabilistic
+- Concretization: claude-sonnet / gpt-4o, temperature=0
+- Mission concretization: higher-capability model (sonnet/gpt-4o)
+- Scope review: provider default model (haiku/gpt-4o-mini)
+- Validation: deterministic structural checks, no LLM
+- Pinning: SHA-256 hashes of prompt+output in governance.yaml
+- Version: single source of truth via importlib.metadata
+- Terminal: PTY via Python stdlib pty + WebSocket + xterm.js
+- Resize: binary protocol (0x01 prefix + cols/rows uint16)
+
+### governance.yaml Schema
+- owner: string
+- scope.authorized: list of {action, reason, added}
+- scope.prohibited: list of {action, reason, severity, added}
+- scope.requires_confirmation: list of {action, reason, added}
+- scope.unresolved_ambiguities: list of {text, added, status}
+- escalation: {contact, method, trigger}
+- killswitch: string
+- concretization_pins: list of {field, input_hash, prompt_hash,
+  output_hash, model, provider, temperature, date}
+- governance_history: list of {date, action, tool, version,
+  changed_fields?}
+
+### Tests
+- 217/217 passing
+- CI: GitHub Actions, Python 3.11 + 3.12, green
+- Web tests: TestClient (fastapi), PTY documented as manual-test-only
+
+## Open Items
+
+### Before PyPI
+- Final documentation sync (this commit)
+
+### After PyPI
+- Dev.to / LinkedIn article: "AgentGuard is live"
+- v0.8.0: Intent-Aware Live Observer (drift detection via JSONL)
+- Web-UI v0.8: inline governance editor
+- Homebrew formula
+
+## Key Files
+
+**Python backend:**
+- `agentguard/web/server.py` — FastAPI + WebSocket PTY
+- `agentguard/checks/preflight.py` — Layer 1
+- `agentguard/enforcement/enforcer.py` — Layer 2
+- `agentguard/checks/runtime.py` — Layer 3
+- `agentguard/guided/concretizer.py` — AI concretization
+- `agentguard/guided/validator.py` — structural validation
+- `agentguard/guided/pinning.py` — SHA-256 pinning
+- `agentguard/review/reviewer.py` — governance review
+- `agentguard/ai_review.py` — scope quality review
+- `agentguard/cli.py` — all commands
+- `agentguard/output/renderer.py` — Rich output
+
+**React frontend:**
+- `web/src/App.jsx` — shell, sidebar, project switcher
+- `web/src/components/CheckPanel.jsx` — score ring
+- `web/src/components/GovernanceView.jsx` — scope cards
+- `web/src/components/VerifyPanel.jsx` — pin cards
+- `web/src/components/TerminalPanel.jsx` — xterm.js PTY
+- `web/src/components/InitPanel.jsx` — setup panel
+- `web/src/components/ReviewPanel.jsx` — review panel
+
+## Related
+
+- Dev.to: https://dev.to/mypatric69/the-blind-spot-of-agentic-ai-systems-when-nobody-notices-the-agent-is-stuck-1hkb
+- LinkedIn: https://www.linkedin.com/posts/patric-hayna-6b7b55134_the-blind-spot-of-agentic-ai-systems-when-activity-7467668285891821568-ZXtx
+
+---
+
+## Last updated
+
+2026-06-10 – Auto-synced 15 commit(s) to a166996

agentguard_governance-0.7.0/CLAUDE.md

@@ -0,0 +1,94 @@
+# AgentGuard — CLAUDE.md
+
+## Project Purpose
+AgentGuard is a governance layer for autonomous AI agents. It provides pre-flight checks (Layer 1), runtime enforcement (Layer 2), runtime monitoring (Layer 3), and post-session reporting and audit (Layer 4). The goal is to make AI agents safer by ensuring governance prerequisites are in place before execution begins.
+
+## Architecture Overview (v0.7.0)
+
+```
+agentguard/
+├── checks/
+│   ├── preflight.py      # Layer 1: governance + prompt + harness checks
+│   ├── runtime.py        # Layer 3: loop/stall/burn detection
+│   └── report.py         # Layer 4: post-session governance report
+├── enforcement/
+│   └── enforcer.py       # Layer 2: PreToolUse hook, exit 0/2
+├── guided/
+│   ├── concretizer.py    # AI concretization (sonnet/gpt-4o, temperature=0)
+│   ├── validator.py      # Deterministic structural validation
+│   └── pinning.py        # SHA-256 prompt/output pinning
+├── review/
+│   └── reviewer.py       # Governance review and update cycle
+├── web/
+│   └── server.py         # FastAPI bridge + WebSocket PTY terminal
+├── config/
+│   └── loader.py         # governance.yaml loading, list+string compat
+├── output/
+│   └── renderer.py       # Rich panels, severity colors
+└── cli.py                # All commands wired here
+
+web/                       # React/Vite frontend (built to web/dist/)
+├── src/
+│   ├── App.jsx            # Sidebar layout, project switcher
+│   └── components/
+│       ├── CheckPanel.jsx      # Pre-flight check + score ring
+│       ├── GovernanceView.jsx  # Color-coded scope sections
+│       ├── VerifyPanel.jsx     # Pin verification cards
+│       ├── TerminalPanel.jsx   # xterm.js + WebSocket PTY
+│       ├── InitPanel.jsx       # Setup governance (Run in Terminal)
+│       └── ReviewPanel.jsx     # Review & update (Run in Terminal)
+└── package.json
+```
+
+## Key Design Principles
+
+- Enforcement layer: deterministic, no LLM, exit 0 or 2
+- Concretization layer: LLM with temperature=0, human confirms
+- Monitoring layer: LLM allowed, warnings only, never blocks
+- Validation layer: deterministic, structural checks, no LLM
+
+## Scope
+- Python CLI tool using Click and Rich
+- No external network calls in core logic (API key optional for progress scoring)
+- Target: developers and teams deploying autonomous AI agents
+
+## Code Quality Rules
+
+**YAGNI** — Build only what is specified. No extra abstractions, no speculative features.
+**KISS** — Prefer the simplest implementation that satisfies the requirement.
+**DRY** — Extract shared logic when the same pattern appears 3+ times.
+**Single Responsibility** — Each module does one thing. CLI wires them together.
+
+- No debug logging (`print()` statements) in committed code
+- No commented-out code
+- No unused imports
+- Tests must pass before commit (`pytest --tb=short`)
+- One commit per logical change
+
+## Loop Detection
+If the same approach fails 2+ times in a row:
+1. STOP immediately
+2. Do not retry the same strategy
+3. Propose a fundamentally different approach
+4. After 3 failed iterations: escalate or ask
+
+## Root Cause Analysis
+- Confirm root cause before implementing any fix
+- Do not patch symptoms
+- If root cause is unclear, ask — do not guess
+
+## External APIs & Documentation
+- Always fetch current documentation before diagnosing API issues
+- Never rely on training-data memory for external API behavior
+- If a newer API version or migration guide exists, flag it first
+
+## Testing
+- All new behavior must have a corresponding test
+- Tests live in `tests/` and mirror the module structure
+- Use `tmp_path` pytest fixture for file system tests — never write to the real project root in tests
+
+## Version Management
+- Version is defined ONLY in `pyproject.toml`
+- `agentguard/__init__.py` reads version dynamically via importlib.metadata
+- Never hardcode version in __init__.py
+- On release: update pyproject.toml version only

agentguard_governance-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.