guardian-framework 0.1.0

package/templates/pi/skills/validators/integration-validator.md

@@ -0,0 +1,38 @@
+# Integration Validator Skill
+
+Validates component integration and wiring.
+
+## Context Files
+
+- `.pi/context/checklists.md` — integration checklist
+- `.pi/context/output-formats.md` — report format
+
+## Wiring Checks
+
+```bash
+# 1. Find callers
+grep -r "function_name" src/
+
+# 2. Check imports
+grep -r "import.*module" src/
+
+# 3. Verify registration (if tool/plugin)
+grep -r "register" [registry file]
+```
+
+## Focus Areas
+
+1. **Interface contracts** — signatures match callers
+2. **Data flow** — types consistent across boundaries
+3. **Error propagation** — errors handled at integration points
+
+## Tools
+
+- Grep: Find wiring
+- LSP: Navigate definitions
+- Read: Review interfaces
+- Bash: Run integration tests
+
+## Output
+
+Use `.pi/context/output-formats.md` → "Wiring Check Report"

package/templates/pi/skills/validators/model-registry.md

@@ -0,0 +1,96 @@
+---
+name: model-registry
+description: Model capability scoring system with intelligence/speed/cost ratings and auto-model selection by task type.
+model: inherit
+tools: [Read]
+---
+
+# Model Registry
+
+Classify models by capability scores to auto-select the right model for each task.
+
+## Capability Dimensions
+
+Each model is scored on a 1–5 scale:
+
+| Dimension | Meaning |
+|-----------|---------|
+| **Intelligence** | Reasoning quality, code understanding, accuracy |
+| **Speed** | Response time (5 = sub-second, 1 = multi-minute) |
+| **Cost** | Price efficiency (5 = cheapest, 1 = most expensive) |
+
+## Model Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `vision` | Can process images |
+| `reasoning` | Extended thinking / chain-of-thought |
+| `tools` | Supports tool/function calling |
+| `coding` | Optimized for code generation |
+
+## Auto-Selection by Task
+
+| Task Type | Recommended Tier | Example Models |
+|-----------|-----------------|----------------|
+| Architecture planning | Intelligence 5 | Opus, GPT-5, Gemini Pro |
+| Complex code changes | Intelligence 4–5 | Sonnet, GPT-4, Codex |
+| Quick edits / fixes | Speed 4+ | GPT-4-mini, Haiku |
+| Inline autocomplete | Speed 5 | GPT-nano, Cerebras, Groq |
+| Bulk code review | Cost 4+ | Flash, Groq, Cerebras |
+| Security audit | Intelligence 5 + reasoning | Opus, Grok Reasoning |
+| File exploration | Speed 4+ | GPT-4-mini, Flash |
+| Test writing | Intelligence 3–4 | Sonnet, GPT-4-mini |
+
+## Context Windows
+
+| Tier | Context Window | Models |
+|------|---------------|--------|
+| Large | 1M+ tokens | GPT-5, Gemini Pro/Flash, xAI Grok |
+| Standard | 200K tokens | Claude Opus/Sonnet/Haiku |
+| Small | 128K tokens | GPT-4 variants, DeepSeek |
+| Minimal | 32K tokens | Local GGUF models |
+
+## Pricing Tiers
+
+| Tier | Input ($/M tokens) | Output ($/M tokens) |
+|------|-------------------|--------------------|
+| Premium | $5–15 | $15–75 |
+| Standard | $1–3 | $5–15 |
+| Budget | $0.1–0.5 | $0.4–2.5 |
+| Local | $0 | $0 |
+
+## Model Selection API
+
+```typescript
+interface ModelInfo {
+  id: string;
+  label: string;
+  hint: string;            // Short display name
+  description: string;     // One-line description
+  capabilities: {
+    intelligence: 1|2|3|4|5;
+    speed: 1|2|3|4|5;
+    cost: 1|2|3|4|5;
+  };
+  tags?: ("vision"|"reasoning"|"tools"|"coding")[];
+  contextLimit: number;    // Approximate context window
+}
+
+function selectModel(task: string): ModelInfo {
+  // Auto-select based on task complexity
+}
+```
+
+## Provider Support
+
+| Provider | Native SDK | Keyless |
+|----------|-----------|---------|
+| OpenAI | @ai-sdk/openai | No |
+| Anthropic | @ai-sdk/anthropic | No |
+| Google | @ai-sdk/google | No |
+| xAI | @ai-sdk/xai | No |
+| Groq | @ai-sdk/groq | No |
+| Cerebras | @ai-sdk/cerebras | No |
+| OpenRouter | @ai-sdk/openai-compatible | No |
+| OpenAI-Compatible | @ai-sdk/openai-compatible | Yes |
+| LM Studio | @ai-sdk/openai-compatible | Yes |

package/templates/pi/skills/validators/operations-validator.md

@@ -0,0 +1,34 @@
+# Operations Validator Skill
+
+Validates production readiness. Checks tracing, cancellation, atomic writes.
+
+## Context Files
+
+- `.pi/context/checklists.md` — operations checklist
+- `.pi/context/patterns.md` — implementation patterns
+- `.pi/context/output-formats.md` — report format
+
+## Automated Validation
+
+Run `.pi/scripts/validate-operations.sh` for:
+- Tracing on public functions
+- CancellationToken/AbortController usage
+- Atomic write pattern
+- Blocking calls in async context
+
+## Manual Validation (LLM)
+
+Focus on:
+1. **Business logic** reliability
+2. **Complex cancellation** scenarios
+3. **Error recovery** strategies
+
+## Tools
+
+- Grep: Find patterns
+- Read: Review implementation
+- Bash: Run validation scripts
+
+## Output
+
+Use `.pi/context/output-formats.md` → "Validation Report"

package/templates/pi/skills/validators/security-guards.md

@@ -0,0 +1,72 @@
+---
+name: security-guards
+description: Pre-execution path safety and command deny-list for AI tool calls. Blocks reads of sensitive files and writes to protected directories.
+model: inherit
+tools: [Read]
+---
+
+# Security Guards
+
+Defense-in-depth guards for AI tool execution. These are **pre-execution** checks — they run BEFORE the tool executes, not after.
+
+## Path Safety: Read Blocklist
+
+**Never allow reads** of files matching these patterns:
+
+### Sensitive Basenames
+- `.env*` (`.env`, `.env.local`, `.env.production`, etc.)
+- `*.pem`, `*.key`, `*.p12`, `*.pfx` (private keys)
+- `id_rsa*`, `id_dsa*`, `id_ecdsa*`, `id_ed25519*` (SSH keys)
+- `known_hosts`, `authorized_keys`, `htpasswd`
+- `.netrc`, `credentials`, `.pgpass`
+- `.npmrc`, `.pypirc`
+- `secrets.json`, `secrets.yaml`, `secrets.yml`, `secrets.toml`
+
+### Protected Path Segments
+- `/.ssh/`, `/.gnupg/`
+- `/.aws/`, `/.azure/`, `/.kube/`
+- `/.docker/`, `/.config/gh/`, `/.config/git/`
+- `/.git/` (git internals)
+
+## Path Safety: Write Blocklist
+
+Writes inherit all read restrictions, **plus**:
+
+### Forbidden System Prefixes
+- `/etc/`, `/var/db/`, `/System/`
+- `/Library/Keychains/`
+- `/private/etc/`, `/private/var/db/`
+
+## Shell Command Deny-list
+
+**Hard-block** these shell commands even after user approval:
+
+| Pattern | Reason |
+|---------|--------|
+| `rm -rf /` (and variants) | Recursive filesystem deletion |
+| `--no-preserve-root` | Override root protection |
+| `dd of=/dev/disk*`, `dd of=/dev/sd*`, `dd of=/dev/nvme*` | Raw disk overwrite |
+| `mkfs*`, `fdisk`, `parted` | Disk formatting |
+| `diskutil eraseDisk` | Mac disk erase |
+| `curl\|sh`, `wget\|sh`, `curl\|bash` | Remote code execution |
+| `sudo` | Privilege escalation |
+| `terraform destroy` | Infrastructure teardown |
+| `kubectl delete` | K8s resource deletion |
+| `aws s3 rm --recursive` | Bulk cloud deletion |
+| `shutdown`, `reboot`, `halt`, `poweroff` | System power operations |
+
+## Read-Before-Edit Invariant
+
+All file mutations (`edit`, `multi_edit`, `write_file`) **require** a prior `read_file` on the same path in the current session. This prevents:
+- Blind overwrites of unknown files
+- Stale edits on changed content
+- Accidental data loss
+
+## Implementation Note
+
+These guards are implemented in:
+- `.pi/extensions/bash-guard.ts` — runtime command blocking
+- `.pi/scripts/validate-security.sh` — post-hoc validation
+- `.pi/skills/agents/security-validator.md` — agent-level security review
+
+Apply guards on **both** read and write paths. Do not bypass them.

package/templates/pi/skills/validators/security-validator.md

@@ -0,0 +1,41 @@
+# Security Validator Skill
+
+Validates security requirements. Checks OWASP Top 10, secrets, injection, path traversal.
+
+## Context Files
+
+- `.pi/context/checklists.md` — security checklist
+- `.pi/context/output-formats.md` — report format
+
+## Automated Checks
+
+Run `.pi/scripts/validate-security.sh` for:
+- Hardcoded secrets detection
+- SQL/command injection patterns
+- Path traversal vulnerabilities
+- Unsafe deserialization
+
+## Manual Checks (LLM)
+
+Focus on:
+1. **Logic errors** scripts can't detect
+2. **Business logic vulnerabilities**
+3. **Complex auth flows**
+
+## OWASP Top 10 Focus
+
+| ID | Issue | Check |
+|----|-------|-------|
+| A01 | Broken Access Control | Hardcoded credentials, auth checks |
+| A03 | Injection | SQL, command, XSS, path traversal |
+| A09 | Logging Failures | Sensitive data in logs |
+
+## Tools
+
+- Grep: Find patterns
+- Read: Review code
+- Bash: Run security scripts
+
+## Output
+
+Use `.pi/context/output-formats.md` → "Security Audit Report"

package/templates/pi/skills/validators/system-prompt-tiers.md

@@ -0,0 +1,69 @@
+---
+name: system-prompt-tiers
+description: Tiered system prompt architecture. Uses full prompts for capable models and compressed prompts for fast/cheap models to optimize token usage.
+model: inherit
+tools: [Read]
+---
+
+# System Prompt Tiers
+
+Different models have different capabilities, costs, and context needs. Use the right prompt tier for the right model to optimize both quality and token spend.
+
+## Full Tier (Intelligence Score 4–5)
+
+**For:** Claude Opus/Sonnet, GPT-4/5, Gemini Pro, Grok Reasoning
+
+Complete system prompt with:
+- Detailed environment description with `<env>` block format
+- Operating principles (execute don't echo, chain actions, ask only when stuck)
+- Full tool descriptions and budgets
+- Editing rules (read-before-edit, exact string replacement)
+- Path resolution rules
+- Shell behavior (persistent sessions, background processes)
+- Output style guidelines (terse, no filler)
+
+## Lite Tier (Intelligence Score 1–3, Speed Score 4–5)
+
+**For:** GPT-4o-mini, Claude Haiku, Gemini Flash, Cerebras, Groq fast models
+
+Compressed system prompt (~40% of full size) with:
+- Essential operating principles only
+- Tool list without detailed descriptions
+- Core editing rules (read-before-edit)
+- Key path resolution rule
+- Minimal output style guidance
+
+## Auto-Selection Rules
+
+| Model Type | Tier | Rationale |
+|------------|------|-----------|
+| Flagship / reasoning | Full | Benefits from detailed instructions |
+| Balanced (Sonnet, GPT-4-mini) | Full | Handles context well, worth the tokens |
+| Fast / cheap (Haiku, Flash, nano) | Lite | Token budget matters more than nuance |
+| Ultra-fast (Cerebras, Groq LPU) | Lite | Sub-second responses need minimal prompt |
+| Local / GGUF | Lite | Limited context, slower token throughput |
+
+## Token Savings
+
+| Model | Full Prompt | Lite Prompt | Savings |
+|-------|------------|-------------|---------|
+| GPT-4o-mini | ~1,200 tokens | ~450 tokens | ~750 tokens/turn |
+| Claude Haiku | ~1,200 tokens | ~450 tokens | ~750 tokens/turn |
+| Gemini Flash | ~1,200 tokens | ~450 tokens | ~750 tokens/turn |
+
+At 20 turns per session, this saves **15,000 tokens** on fast models alone.
+
+## Model Classification
+
+```
+Intelligence 5: Opus, GPT-5, Gemini Pro, Grok Reasoning, DeepSeek Pro
+Intelligence 4: Sonnet, GPT-4, GPT-4-mini, Gemini Stable, Grok Fast
+Intelligence 3: Haiku, GPT-nano, Flash, Cerebras, Groq, local GGUF
+Intelligence 1-2: Tiny models, heavily quantized local models
+```
+
+## When to Override
+
+- User explicitly requests a tier via `/prompt full` or `/prompt lite`
+- Task complexity exceeds the current tier's capability (escalate to full)
+- Token budget is critically low (downgrade to lite mid-session)

package/templates/pi/skills/validators/test-validator.md

@@ -0,0 +1,33 @@
+# Test Validator Skill
+
+Validates test coverage and quality. Post-code only (automated).
+
+## Context Files
+
+- `.pi/context/checklists.md` — test checklist
+- `.pi/context/output-formats.md` — report format
+
+## Automated Validation
+
+Run `.pi/scripts/validate-tests.sh` for:
+- Unit tests execution
+- Integration tests execution
+- Coverage measurement
+- Test failure analysis
+
+## Manual Validation (LLM)
+
+Focus on:
+1. **Edge case coverage** — empty inputs, boundaries, errors
+2. **Test quality** — specific assertions, deterministic
+3. **Missing tests** for new functionality
+
+## Tools
+
+- Bash: Run tests
+- Read: Review test code
+- Glob: Find test files
+
+## Output
+
+Use `.pi/context/output-formats.md` → "Validation Report"

package/templates/pi/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared types for pi extensions.
+ *
+ * The pi coding agent (`@mariozechner/pi-coding-agent`) does not currently
+ * publish a formal TypeScript type definition for its extension context.
+ * These types mirror the runtime shape so template extensions can type-check
+ * without `any`.
+ */
+
+export interface PiExtensionContext {
+	cwd: string;
+	hasUI: boolean;
+	ui: PiUI;
+	session: {
+		tools: Record<string, { execute: (...args: unknown[]) => unknown }>;
+	};
+}
+
+export interface PiUI {
+	notify(message: string, type: "info" | "success" | "warn" | "error" | "warning"): void;
+	confirm(title: string, message: string): Promise<boolean>;
+	input(title: string, placeholder?: string): Promise<string | null>;
+	select(title: string, options: string[]): Promise<string | null>;
+	setStatus(key: string, message: string | null): void;
+	setWidget(key: string, lines: string[]): void;
+	custom<T>(
+		render: (tui: PiTUI, theme: PiTheme, kb: unknown, done: (value: T) => void) => PiCustomRenderer,
+		options?: { overlay?: boolean },
+	): Promise<T | null>;
+	theme: PiTheme;
+}
+
+export interface PiTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+	muted(text: string): string;
+	dim(text: string): string;
+	accent(text: string): string;
+	warning(text: string): string;
+}
+
+export interface PiTUI {
+	requestRender(): void;
+}
+
+export interface PiCustomRenderer {
+	render(w: unknown): void;
+	invalidate(): void;
+	handleInput(data: string): void;
+}
+
+export interface SelectItem {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+/** Minimal retry options used across extensions. */
+export interface RetryOptions {
+	maxAttempts?: number;
+	baseDelayMs?: number;
+}

package/templates/pi/validators/README.md

@@ -0,0 +1,93 @@
+# Guardian TOML Validators
+
+Declarative validation rules with inline tests. Inspired by RTK's TOML filter pipeline.
+
+## Quick Start
+
+```bash
+# Run all validators
+guardian validate
+
+# Run a specific TOML validator
+guardian validate --filter test-results
+
+# Verify all inline tests pass
+guardian validate --verify
+
+# Run with verbose output
+guardian validate --verbose
+```
+
+## Pipeline Stages
+
+Each filter applies these stages in order:
+
+1. **strip_ansi** — Remove ANSI escape codes
+2. **replace** — Regex substitutions, line-by-line, chainable
+3. **match_output** — Short-circuit: if blob matches, return message immediately
+4. **strip/keep_lines** — Filter lines by regex
+5. **truncate_lines_at** — Truncate each line to N chars
+6. **head/tail_lines** — Keep first/last N lines
+7. **max_lines** — Absolute line cap
+8. **on_empty** — Message if result is empty
+
+## File Location
+
+Validators are loaded from:
+
+1. `.pi/validators/*.toml` — project-local (trust-gated)
+2. `~/.config/guardian/filters.toml` — user-global
+3. Built-in — from Guardian templates
+
+## Trust Model
+
+Project-local validators require explicit trust:
+
+```bash
+# Review and trust
+guardian trust .pi/validators/custom.toml
+
+# Revoke trust
+guardian untrust .pi/validators/custom.toml
+
+# List trusted files
+guardian trust --list
+```
+
+Or bypass for CI: `GUARDIAN_TRUST_OVERRIDE=1 guardian validate`
+
+## Filter Schema
+
+```toml
+schema_version = 1
+
+[filters.my-validator]
+command = "build"                    # Command to match
+description = "Filter build output"   # Human-readable description
+strip_ansi = true                     # Remove ANSI codes
+replace = [                           # Regex substitutions (stage 2)
+  { pattern = "^noise$", replacement = "" }
+]
+match_output = [                      # Short-circuit rules (stage 3)
+  { pattern = "Build failed", message = "❌ Build failed" }
+]
+keep_lines_matching = ["error"]       # Keep only error lines (stage 4)
+truncate_lines_at = 120               # Max chars per line (stage 5)
+head_lines = 10                       # Keep first N lines (stage 6)
+tail_lines = 5                        # Keep last N lines (stage 6)
+max_lines = 50                        # Absolute cap (stage 7)
+on_empty = "✅ All clean"            # Empty result message (stage 8)
+
+# Inline tests (self-verifying)
+[[tests.my-validator]]
+name = "strips noise"
+input = "noise line\nerror: something\nmore noise"
+expected = "error: something"
+```
+
+## Adding Custom Validators
+
+1. Create `.pi/validators/custom.toml`
+2. Define filters with `[[tests.*]]` blocks
+3. Run `guardian validate --verify` to test
+4. Run `guardian trust .pi/validators/custom.toml` to enable