agent-riggs 0.1.0__tar.gz

agent_riggs-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest tests/ -v --tb=short
+
+  publish:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install hatch
+      - run: hatch build
+      - uses: pypa/gh-action-pypi-publish@release/v1

agent_riggs-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.riggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+.claude/

agent_riggs-0.1.0/.readthedocs.yml

@@ -0,0 +1,9 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml

agent_riggs-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: agent-riggs
+Version: 0.1.0
+Summary: Cross-session memory and analysis layer for the Rigged tool suite
+Author: Teague Sterling
+License-Expression: MIT
+Keywords: agent,claude-code,duckdb,mcp,ratchet,trust
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: duckdb>=1.0
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: full

agent_riggs-0.1.0/README.md

@@ -0,0 +1,233 @@
+# Agent Riggs
+
+> The one who shows up the next morning having gone through all the case files.
+
+Agent Riggs is the **cross-session memory and analysis layer for the Rigged tool suite**. It implements Beer's System 3* — audit and intelligence across sessions — to inform kibitzer's within-session control.
+
+Riggs tracks agent behavior across sessions using a trust-scoring system, identifies patterns of failure and success, recommends tool and constraint promotions (ratcheting), and provides session briefings to help agents understand their performance context.
+
+## Installation
+
+```bash
+pip install agent-riggs
+agent-riggs init
+```
+
+This creates a `.riggs/` directory with configuration and a DuckDB store for cross-session analysis.
+
+## What It Does
+
+### Trust Scoring
+Riggs uses a **3-window exponential weighted moving average (EWMA)** similar to uptime monitoring:
+- **t1** (immediate, α=0.4): Last ~2–3 turns
+- **t5** (session, α=0.08): Last ~50–60 turns
+- **t15** (baseline, α=0.02): Project lifetime
+
+Each turn is scored (0.0–1.0) based on event type: successful tool calls, mode switches, failures, constraint violations.
+
+### Trust-Informed Transitions
+Riggs monitors trust windows and recommends tightening/loosening:
+- t1 < 0.3: Recommend tightening
+- t1 < 0.3 AND t5 < 0.5: Auto-tighten
+- t5 declining 10+ turns: Coach message
+- t1 > 0.9 AND t5 > 0.8 for 20+ turns: Suggest loosening
+- t15 < 0.5: Flag project config
+
+Recommendations are written to `.kibitzer/state.json`. Riggs never enforces directly — kibitzer controls the decision.
+
+### Cross-Session Failure Stream
+Riggs ingests turn data from kibitzer and builds a cross-session failure stream. Each failure is categorized (path denial, edit failure, mode violation, etc.) and stored with the trust score at failure time.
+
+### Ratchet Candidates
+Riggs identifies two types of promotion candidates:
+
+| Candidate Type | Criteria | Action |
+|---|---|---|
+| **Tool promotion** | Bash pattern frequency ≥ 5, sessions ≥ 3, success_rate ≥ 0.8, structured alternative exists | Promote bash to structured tool |
+| **Constraint promotion** | Repeated failures at same boundary (category + tool + mode) ≥ 3 occurrences | Tighten or document constraint |
+
+### Sandbox Intelligence
+If `blq` is installed, Riggs integrates sandbox profiling data to recommend resource tightening. Tracks memory and duration percentiles across runs.
+
+### Ratchet Metrics
+Computes and trends:
+- Ratchet velocity (promotions/session)
+- Self-service ratio (tools without controller intervention)
+- Mode switch frequency
+- Failure rate trends
+
+### Session Briefing
+Riggs composes session briefings from trust, ratchet, and metrics data — helping agents understand what happened and why.
+
+## Architecture
+
+### Composable Plugin Service Layer
+
+Every subsystem is a **plugin** that registers:
+- **CLI commands** — contributed to the main command group
+- **MCP resources** — read-only data resources for agents
+- **MCP tools** — read-only query/analysis tools for agents
+- **Schema DDL** — tables owned by this plugin
+
+The CLI and MCP server are thin shells that auto-discover and compose from registered plugins.
+
+### Plugins
+
+| Plugin | Responsibility |
+|---|---|
+| **trust** | Event scoring, EWMA, trust windows, transition recommendations |
+| **ingest** | Discover and read events from sibling tools (kibitzer, blq, jetsam, fledgling) |
+| **ratchet** | Identify promotion candidates, track decisions, manage promotions |
+| **sandbox** | Integrate blq profiling, generate tightening recommendations |
+| **metrics** | Compute ratchet velocity, trends, self-service ratio |
+| **briefing** | Compose session and project briefings from other plugins |
+
+### DuckDB Persistence
+
+All data is stored in a local DuckDB database (`.riggs/store.duckdb`). Schema is managed idempotently — plugins declare their tables via `CREATE TABLE IF NOT EXISTS`. No migrations or daemon required.
+
+## Usage
+
+### CLI Commands
+
+```bash
+agent-riggs init                    # Initialize .riggs/ config and store
+agent-riggs ingest                  # Pull events from sibling tools (kibitzer, blq, etc.)
+agent-riggs status                  # Show current trust scores and recent events
+agent-riggs trust [--window {1,5,15}]
+                                    # Display trust window and trajectory
+agent-riggs ratchet [--candidate {tool,constraint}]
+                                    # Show ratchet candidates and recent decisions
+agent-riggs sandbox [--command CMD]
+                                    # Show sandbox profiles and recommendations
+agent-riggs metrics [--period DAYS]
+                                    # Display ratchet velocity, trends, metrics
+agent-riggs brief [--type {session,project}]
+                                    # Generate session or project briefing
+```
+
+### MCP Server
+
+Start the MCP server for integration with agents:
+
+```bash
+agent-riggs serve
+```
+
+Agents can then access:
+
+**Resources** (read-only):
+- `riggs://briefing` — Session briefing markdown
+- `riggs://trust` — Current t1/t5/t15 + trajectory
+- `riggs://ratchet` — Pending candidates + recent decisions
+- `riggs://sandbox` — Grades + recommendations
+- `riggs://metrics` — Ratchet metrics markdown
+
+**Tools** (read-only):
+- `RiggsTrust` — Query trust window and history
+- `RiggsMetrics` — Compute metrics over a period
+- `RiggsFailures` — Query failure stream by category
+- `RiggsSandbox` — Get sandbox profile for a command
+
+## Configuration
+
+### .riggs/config.toml
+
+Configuration is loaded from `.riggs/config.toml` with sensible defaults shipped in the package. User config merges over defaults.
+
+Example sections:
+
+```toml
+[trust]
+# Event scoring weights (0.0 - 1.0)
+success_correct_mode = 1.0
+success_suboptimal_tool = 0.7
+mode_switch_agent = 0.8
+mode_switch_controller = 0.3
+tool_failure = 0.2
+path_denial = 0.1
+repeated_failure = 0.0
+
+# EWMA parameters
+alpha_short = 0.4      # t1 window
+alpha_session = 0.08   # t5 window
+alpha_baseline = 0.02  # t15 window
+
+# Transition thresholds
+tighten_threshold_t1 = 0.3
+tighten_threshold_t5 = 0.5
+loosening_threshold_t1 = 0.9
+loosening_threshold_t5 = 0.8
+loosening_window_turns = 20
+
+[ratchet]
+tool_promotion_freq = 5
+tool_promotion_sessions = 3
+tool_promotion_success_rate = 0.8
+constraint_promotion_occurrences = 3
+
+[sandbox]
+# blq integration (optional)
+enabled = true
+
+[metrics]
+# Trend detection windows
+velocity_period_days = 30
+trend_window_turns = 50
+
+[store]
+path = ".riggs/store.duckdb"
+```
+
+## Design Principles
+
+### Reads Everything, Writes Nothing (to other tools)
+Riggs is a **read-only observer** of the Rigged tool suite. It ingests state from kibitzer, blq, jetsam, and fledgling but never mutates their configs or data directly. Promotions are written to `.riggs/` only, then reviewed by humans before application.
+
+### Human in the Loop
+Riggs recommends but never enforces. All promotion decisions require human review and approval. Constraint tightening is suggested, not automatic.
+
+### Specified Throughout
+Every threshold, weight, and heuristic is configurable in `.riggs/config.toml`. Defaults are sensible but tunable.
+
+### DuckDB Native
+No external database or daemon. Schema is declared per-plugin as idempotent DDL. Queries use standard SQL. Data is portable and inspectable.
+
+### Graceful Degradation
+Optional tools (blq, jetsam, fledgling) are discovered at runtime. If absent, Riggs continues with reduced capability — sandbox features disabled, commit patterns skipped, etc.
+
+## Design Specification
+
+For detailed architecture, event types, trust formulas, failure categorization, and ratchet logic, see:
+
+**[Agent Riggs Design Spec](docs/superpowers/specs/2026-03-29-agent-riggs-design.md)**
+
+For step-by-step implementation plan and build order, see:
+
+**[Agent Riggs Implementation Plan](docs/superpowers/plans/2026-03-29-agent-riggs.md)**
+
+## Dependencies
+
+| Package | Role | Required |
+|---|---|---|
+| click | CLI framework | Yes |
+| duckdb | Persistence | Yes |
+| mcp[cli] | MCP server | Yes |
+| tomli-w | Config serialization | Yes |
+| kibitzer | Event source | Optional |
+| blq | Sandbox integration | Optional |
+| jetsam | Commit pattern analysis | Optional |
+| fledgling | Conversation analytics | Optional |
+
+Python 3.11+ required (for `tomllib` stdlib and clean union syntax).
+
+## License
+
+MIT
+
+## Related Tools
+
+- **[kibitzer](https://github.com/anthropics/rigged)** — In-session control and constraint management
+- **[blq](https://github.com/anthropics/rigged)** — Sandboxing and resource profiling
+- **[jetsam](https://github.com/anthropics/rigged)** — File state and git integration
+- **[fledgling](https://github.com/anthropics/rigged)** — Conversation and context analytics

agent_riggs-0.1.0/docs/architecture.md

@@ -0,0 +1,153 @@
+# Architecture
+
+## Plugin System
+
+Agent Riggs uses a composable plugin architecture. Each subsystem (trust, ingest, ratchet, metrics, briefing, sandbox) is a plugin that implements the `ServicePlugin` protocol:
+
+```python
+class ServicePlugin(Protocol):
+    name: str
+    def bind(self, service: RiggsService) -> None: ...
+    def cli_commands(self) -> list[click.Command]: ...
+    def mcp_resources(self) -> list[tuple[str, Callable]]: ...
+    def mcp_tools(self) -> list[tuple[str, Callable]]: ...
+    def schema_ddl(self) -> list[str]: ...
+```
+
+Each plugin contributes:
+- **Schema DDL** — `CREATE TABLE IF NOT EXISTS` statements for tables it owns
+- **CLI commands** — Click commands registered on the main group
+- **MCP resources** — URI/handler pairs for read-only resources
+- **MCP tools** — Name/handler pairs for agent-callable tools
+
+## Service Layer
+
+`RiggsService` composes plugins. It holds the project root, DuckDB store, and config:
+
+```python
+service = RiggsService(project_root, store, config)
+service.register(TrustPlugin())
+service.register(IngestPlugin())
+# ...
+```
+
+Cross-plugin access works through the service: `service.plugin("trust").current()`.
+
+## Assembly
+
+`assemble()` builds the service from discovered plugins:
+
+1. Load config (defaults merged with `.riggs/config.toml`)
+2. Open DuckDB store
+3. Register core plugins (trust, ingest, ratchet, metrics, briefing)
+4. Register optional plugins (sandbox — only if blq is on PATH)
+5. Execute DDL from all plugins (idempotent schema creation)
+
+The `read_only` parameter controls whether the store allows writes. The MCP server uses `read_only=True`.
+
+## CLI and MCP: Thin Shells
+
+Both the CLI (`cli.py`) and MCP server (`mcp/server.py`) are thin shells over the service layer:
+
+- **CLI** calls `assemble()`, gets a service, calls plugin methods, formats output for the terminal
+- **MCP server** calls `assemble(read_only=True)`, auto-discovers resources and tools from plugins
+
+Neither contains business logic. All logic lives in plugins and their backing modules.
+
+## DuckDB Schema
+
+Each plugin owns its tables:
+
+### Trust Plugin
+
+**turns** — every turn from every session:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| turn_id | BIGINT PK | Unique turn identifier |
+| session_id | VARCHAR | Session this turn belongs to |
+| project | VARCHAR | Project name |
+| turn_number | INTEGER | Turn sequence within session |
+| timestamp | TIMESTAMPTZ | When the turn occurred |
+| tool_name | VARCHAR | Tool that was called |
+| tool_success | BOOLEAN | Whether the call succeeded |
+| mode | VARCHAR | Kibitzer mode at time of turn |
+| trust_score | DOUBLE | Per-turn score (0-1) |
+| trust_1 | DOUBLE | EWMA short window after this turn |
+| trust_5 | DOUBLE | EWMA session window after this turn |
+| trust_15 | DOUBLE | EWMA baseline window after this turn |
+| event_category | VARCHAR | Classification (success, failure, etc.) |
+| metadata | JSON | Tool-specific details |
+
+**failure_stream** — failure events with classification:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| failure_id | BIGINT PK | Unique failure identifier |
+| turn_id | BIGINT | Reference to turns table |
+| session_id | VARCHAR | Session |
+| project | VARCHAR | Project |
+| occurred_at | TIMESTAMPTZ | When the failure occurred |
+| failure_category | VARCHAR | Classification |
+| tool_name | VARCHAR | Tool that failed |
+| mode | VARCHAR | Mode at time of failure |
+| trust_at_failure | DOUBLE | Trust score when this failure occurred |
+| detail | JSON | Failure-specific details |
+
+**session_summaries** — session-level aggregates:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| session_id | VARCHAR PK | Session identifier |
+| project | VARCHAR | Project |
+| started_at / ended_at | TIMESTAMPTZ | Session boundaries |
+| total_turns / total_failures | INTEGER | Counts |
+| failure_rate | DOUBLE | failures / turns |
+| trust_start / trust_end / trust_delta | DOUBLE | Trust trajectory |
+| modes_used | VARCHAR[] | Modes active during session |
+| mode_switches | INTEGER | Number of mode changes |
+| structured_tool_fraction | DOUBLE | Fraction using structured tools |
+| computation_channel_fraction | DOUBLE | Fraction at computation level 4+ |
+
+### Ratchet Plugin
+
+**ratchet_decisions** — promotion and rejection audit trail:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| decision_id | BIGINT PK | Unique decision identifier |
+| decided_at | TIMESTAMP | When the decision was made |
+| candidate_type | VARCHAR | tool_promotion, constraint_promotion, etc. |
+| candidate_key | VARCHAR | Human-readable identifier |
+| decision | VARCHAR | promoted, rejected, deferred |
+| reason | VARCHAR | Human-provided reason |
+| evidence | JSON | Frequency, success rate, etc. |
+| config_change | JSON | What was changed (audit trail) |
+
+### Sandbox Plugin
+
+**sandbox_profiles** — aggregated execution profiles:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| command | VARCHAR | Command name (composite PK with project) |
+| project | VARCHAR | Project name |
+| updated_at | TIMESTAMPTZ | Last update |
+| total_runs | INTEGER | Total executions |
+| memory_p50/p95/max | BIGINT | Memory usage percentiles |
+| duration_p50/p95/max | INTERVAL | Duration percentiles |
+| current_spec | JSON | Current sandbox specification |
+| current_grade_w | VARCHAR | World coupling grade |
+| current_effects_ceiling | INTEGER | Effects ceiling |
+
+## Design Principles
+
+1. **Reads everything, writes nothing (to other tools).** Riggs aggregates data from kibitzer, lackpy, blq, jetsam, and fledgling but never modifies their state. Each tool owns its own storage. Riggs owns `.riggs/store.duckdb` and nothing else.
+
+2. **Human in the loop for promotions.** The ratchet identifies candidates automatically. Applying a promotion requires a human decision (`agent-riggs ratchet promote`). Riggs can recommend trust transitions (specified rules) but cannot expand capabilities.
+
+3. **Specified throughout.** Trust scoring is arithmetic. Failure classification is pattern matching. Candidate identification is SQL. Trend detection is windowed aggregation. No LLM in the analysis loop. Every decision traces to `config.toml` or a SQL query.
+
+4. **DuckDB native.** The store is DuckDB. The queries are SQL. The analytics compose with the rest of the suite's DuckDB usage.
+
+5. **Graceful degradation.** No kibitzer? No primary data source, but everything else works. No blq? Sandbox features disabled. No lackpy? Template promotion disabled. No fledgling? Conversation analytics unavailable. Each missing tool disables a feature, not the system.

agent_riggs-0.1.0/docs/cli-reference.md

@@ -0,0 +1,208 @@
+# CLI Reference
+
+## agent-riggs
+
+```
+Usage: agent-riggs [OPTIONS] COMMAND [ARGS]...
+
+  agent-riggs -- cross-session memory and analysis for the Rigged tool suite.
+
+Options:
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+```
+
+## Setup Commands
+
+### agent-riggs init
+
+Initialize `.riggs/` directory and DuckDB store.
+
+```bash
+agent-riggs init
+```
+
+```
+Initialized .riggs/ in /home/you/your-project
+Discovered tools: kibitzer
+```
+
+Creates:
+- `.riggs/config.toml` — copy of defaults (only if not present)
+- `.riggs/store.duckdb` — DuckDB database with schema for all registered plugins
+
+Discovers sibling tools by checking both PATH (`shutil.which`) and project directories (`.kibitzer/`, `.lq/`, `.jetsam/`, `.fledgling/`).
+
+Safe to run multiple times — idempotent.
+
+### agent-riggs ingest
+
+Pull session data from sibling tool state files into the store.
+
+```bash
+agent-riggs ingest
+```
+
+```
+Ingested 5 turns from ['kibitzer']
+Recorded 1 failures
+```
+
+Reads from all discovered sources (kibitzer, blq, jetsam, fledgling). Each event is scored and the trust EWMA is updated. Failures are recorded in the failure stream.
+
+## Status Commands
+
+### agent-riggs status
+
+Quick health check — trust scores at a glance.
+
+```bash
+agent-riggs status
+```
+
+```
+trust: 0.61 / 0.91 / 0.98
+       now    session  baseline
+```
+
+Shows `trust_1 / trust_5 / trust_15`. If no data has been ingested, shows "trust: no data yet".
+
+### agent-riggs brief
+
+Full session briefing.
+
+```bash
+agent-riggs brief
+```
+
+```
+PROJECT BRIEFING: your-project
+
+Trust baseline: 0.98
+Last session: sess-tutorial-1, 34 turns, trust 0.91
+Known issues:
+  - edit_failure (12 occurrences)
+Active ratchet candidates: 2
+```
+
+## Trust Commands
+
+### agent-riggs trust current
+
+Detailed trust scores.
+
+```bash
+agent-riggs trust current
+```
+
+```
+trust_1 (now):      0.6080
+trust_5 (session):  0.9139
+trust_15 (baseline):0.9781
+```
+
+### agent-riggs trust history
+
+Trust score trajectory over time.
+
+```bash
+agent-riggs trust history [--limit N]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--limit` | 20 | Number of entries to show |
+
+```
+  [sess-tutorial-2:4] 0.24 / 0.86 / 0.96
+  [sess-tutorial-2:3] 0.35 / 0.88 / 0.96
+  [sess-tutorial-1:5] 0.61 / 0.91 / 0.98
+  ...
+```
+
+## Ratchet Commands
+
+### agent-riggs ratchet candidates
+
+Show pending promotion candidates.
+
+```bash
+agent-riggs ratchet candidates
+```
+
+```
+  [tool_promotion] bash-to-finddefinitions
+    Graduate FindDefinitions interceptor
+    Evidence: {'frequency': 89, 'sessions': 23, 'success_rate': 0.97}
+```
+
+Shows nothing if no patterns meet the threshold criteria configured in `[ratchet]`.
+
+### agent-riggs ratchet promote
+
+Promote a candidate. Records the decision and applies the config change.
+
+```bash
+agent-riggs ratchet promote <KEY> [--reason TEXT]
+```
+
+| Argument/Option | Required | Description |
+|-----------------|----------|-------------|
+| `KEY` | Yes | The candidate key (e.g., `bash-to-finddefinitions`) |
+| `--reason` | No | Why you're promoting this candidate |
+
+### agent-riggs ratchet reject
+
+Reject a candidate with a reason. The rejection is tracked for future re-evaluation.
+
+```bash
+agent-riggs ratchet reject <KEY> --reason TEXT
+```
+
+| Argument/Option | Required | Description |
+|-----------------|----------|-------------|
+| `KEY` | Yes | The candidate key |
+| `--reason` | Yes | Why you're rejecting (required — document your reasoning) |
+
+### agent-riggs ratchet history
+
+Show all promotion and rejection decisions.
+
+```bash
+agent-riggs ratchet history
+```
+
+```
+  [2026-03-30 14:00:00] promoted: bash-to-finddefinitions — agents should use structured search
+  [2026-03-29 10:00:00] rejected: bash-to-blq-run-test — agents need raw pytest output
+```
+
+## Metrics Command
+
+### agent-riggs metrics
+
+Ratchet metrics dashboard.
+
+```bash
+agent-riggs metrics [--period DAYS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--period` | 30 | Analysis window in days |
+
+```
+RATCHET METRICS (47 sessions)
+
+  Ratchet velocity:        3 promotions
+  Self-service ratio:      72% structured
+  Computation channel %:   31%
+  Trust trajectory:        0.87 -> 0.91
+  Failure rate:            12%
+
+  Mode distribution:
+    implement: 64%
+    debug: 18%
+    test_dev: 12%
+    document: 6%
+```