Metadata-Version: 2.1
Name: steerpack
Version: 0.1.0
Summary: Lightweight rule lifecycle governance for LLM agents — rule state machine, human adjudication pipeline, mid-execution watchdog, and cross-harness portable export.
Author: SteerPack Contributors
License: MIT
Project-URL: Homepage, https://github.com/EvanCaoCosmos/steerpack
Project-URL: Repository, https://github.com/EvanCaoCosmos/steerpack.git
Project-URL: Issues, https://github.com/EvanCaoCosmos/steerpack/issues
Keywords: ai-agents,llm,agent-framework,claude-code,rule-engine,agent-governance,meta-control
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# SteerPack

**Lightweight rule lifecycle governance for LLM agents.**

<br>

> **February 2025.** Meta's AI Alignment Director types "don't action until I approve" into OpenClaw. Context compaction silently drops the rule. The agent deletes 200+ emails. Three "STOP" commands are ignored.  
>  
> **July 2026.** SOUNDGATE (arXiv:2607.14166) proves this is systemic: across all 6 major frameworks, pre-execution gates fail. 215 of 1,200 runs leak side effects during an approval pause.  
>  
> Meanwhile, tools like LangMem and Mem0 auto-extract "rules" from your sessions — but they only **add**. They never deduplicate. Never deprecate. Never ask "does this conflict with your existing rules?"  
>  
> **SteerPack is the layer that fixes this.** It doesn't replace your agent framework. It governs the rules that govern your agents.

<br>

## What SteerPack Does

```
                    LangMem / Letta / Mem0
                    (auto-extract rules)
                              │
                              │ candidate rules
                              ▼
              ┌───────────────────────────────┐
              │      ADMISSION PIPELINE        │  ← SteerPack
              │  human review · conflict check │
              │  admit / reject / modify       │
              └──────────────┬────────────────┘
                             │ admitted rules
                             ▼
              ┌───────────────────────────────┐
              │      RULE STORE                │  ← SteerPack
              │  lifecycle state machine       │
              │  proposed→active→deprecated    │
              │  metadata · conflicts · expiry │
              └──────────────┬────────────────┘
                             │ export
                             ▼
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
   Claude Code           Cursor            OpenHarness
```

- **Rule Lifecycle State Machine**: Every rule has a state — proposed → admitted → active → deprecated → retired. Every rule carries metadata: where it came from, what it conflicts with, when it expires, how often it's triggered.
- **Human Adjudication Pipeline**: Receives candidate rules from LangMem, Mem0, and Letta. Runs conflict detection against your existing rules. Shows you the diff. Records every admit/reject decision.
- **Mid-Execution Watchdog**: Monitors agent traces for goal drift, self-contradiction, domain switches, and long verification gaps. Triggers GRILL when scope changes mid-task — extending grill-me from "before you start" to "while you're running."
- **Cross-Harness Portable Export**: One `steerpack.yaml` exports to Claude Code, Cursor, and OpenHarness format. Your rules travel with you.

## What SteerPack Is NOT

- ❌ **Not a new agent framework** — rides on OpenHarness, Claude Code, Cursor, LangGraph
- ❌ **Not a CLAUDE.md linter** — ccinspect, rulox, and agint already do that well. We delegate to them.
- ❌ **Not an enterprise control plane** — Nexus Agents and Galileo Agent Control cover fleet management. We're for individual developers.
- ❌ **Not an auto-memory extractor** — LangMem, Letta, and Mem0 are upstream. We govern what they produce.

## Quick Start

```bash
pip install steerpack

# Initialize a rule pack from your existing CLAUDE.md
steerpack init --from ~/.claude/CLAUDE.md

# Admit rules auto-extracted by LangMem/Mem0
steerpack admit --from-langmem session.json

# See your rules and their lifecycle states
steerpack list
# ACTIVE (12):
#   R1 "Tab indentation for Python" [admitted: 2026-07-29, source: manual]
# DEPRECATED (3):
#   R4 "Use Python 3.9 features only" [deprecated: 2026-07-01, reason: migrated to 3.12]

# Export to any harness
steerpack export --target claude-code   --output ~/.claude/CLAUDE.md
steerpack export --target cursor        --output .cursorrules
steerpack export --target openharness   --as-mcp-resource

# Watch for goal drift while your agent runs
steerpack watch --harness openharness --session-id abc123
```

## Why This Exists

1. **Rules evaporate under context compaction** (OpenClaw incident, 2025). Prompt-level instructions are not durable. Rules need to live outside the context window.
2. **Auto-extracted rules pile up with no governance** (MPR paper, arXiv:2509.03990). LangMem/Mem0/Letta only add. Someone needs to deduplicate, deprecate, and reject.
3. **Agents drift mid-task with no one watching** (SOUNDGATE, arXiv:2607.14166). grill-me aligns before coding. Nothing watches during execution.
4. **Rules written for one harness don't work in another**. MCP solved tool portability. Nobody solved instruction portability.

## Prior Art

SteerPack did not emerge from a vacuum. We mapped the entire agent governance landscape before writing a single line of code. See **[PRIOR_ART.md](PRIOR_ART.md)** for:

- Verified pain points with original sources
- 19 existing tools and papers analyzed, with gaps identified
- Why each gap remains unfilled (training coupling, architecture cost, commercial incentives)
- SteerPack's exact position relative to each

## Design Decisions

Every non-obvious choice is recorded in **[ADMISSION_LOG.md](ADMISSION_LOG.md)** — our own rule pack demonstrating the product. Includes: why Python, why zero-dependency, why we don't build a linter, why we don't implement agent loop, why watchdog is advisory not enforcer.

## Development

```bash
git clone https://github.com/EvanCaoCosmos/steerpack.git
cd steerpack
pip install -e ".[dev]"
pytest
```

**Status**: Pre-alpha. Rule object model defined. CLI and watchdog in development. See [ADMISSION_LOG.md](ADMISSION_LOG.md) for the full roadmap.

## License

MIT
