grudge-cli 0.1.0__tar.gz

grudge_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grudge contributors
+
+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.

grudge_cli-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.2
+Name: grudge-cli
+Version: 0.1.0
+Summary: Deterministic regression scars for agent mistakes.
+Author: Grudge contributors
+License: MIT
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: typer==0.15.1
+Requires-Dist: click==8.1.8
+Requires-Dist: rich==13.9.4
+Requires-Dist: httpx==0.28.1
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Requires-Dist: pytest-cov==6.0.0; extra == "dev"
+Requires-Dist: hypothesis==6.123.10; extra == "dev"
+Requires-Dist: ruff==0.14.14; extra == "dev"
+Requires-Dist: mypy==1.18.2; extra == "dev"
+
+# Grudge
+
+**Agents repeat mistakes. Grudge makes each one happen exactly once.**
+
+## The problem
+
+Agent failures are often buried in long, provider-dependent transcripts that are difficult to reproduce. A copied transcript can show what happened, but it cannot show whether the live policy would make the same decision when the world changes. Grudge turns one failure into a small, reviewable regression Scar that can run offline and block the same behavior from returning.
+
+## 30-second quickstart
+
+Use Python 3.14.0 or another interpreter supported by `pyproject.toml`, then run
+the complete offline demo from the repository root:
+
+```bash
+pip install -e . && grudge demo
+```
+
+The command opens the local viewer and plays the five-beat story: capture the
+vulnerable run, shrink its world, synthesize a predicate, prove red-on-bad and
+green-on-fixed admission, then reintroduce the bug and block it. The demo is
+offline and deterministic: it uses checked-in fake tools, scripted policies,
+the checked-in Scar, and the fallback predicate; it does not call a provider or
+the public network. For a headless smoke run, use
+`python -m grudge demo --no-browser --fast --json`. For the two-session
+Claude-style hook proof, use `python -m grudge demo --guard --json`.
+
+### Install the local guard
+
+These commands exercise the checkout's Node package from the repository root;
+they do not resolve a package from the npm registry:
+
+```bash
+npm --prefix packages/grudge run build
+npm --prefix packages/grudge run setup:repo
+npm --prefix packages/grudge run doctor:repo
+```
+
+If `grudge` has been published, the equivalent registry workflow is
+`npx grudge-cli ...`. When working from `packages/grudge`, use `node dist/grudge.mjs`
+and add `--cwd ../..` when the hooks should target the repository root. The
+short package-directory commands are `npm run setup:repo` and
+`npm run doctor:repo`. Do not combine `cd packages/grudge` with the
+root-relative path `packages/grudge/dist/grudge.mjs`, or it resolves to
+`packages/grudge/packages/grudge/dist/grudge.mjs`.
+
+Claude Code is the verified **Guard** tier. Codex, Gemini CLI, GitHub Copilot,
+OpenCode, and Windsurf are **Advisory** integrations; Cursor is unverified and
+the installer writes no Cursor files. See [the integration matrix](docs/integrations.md).
+Use `node packages/grudge/dist/grudge.mjs setup --dry-run` to inspect a plan and
+`node packages/grudge/dist/grudge.mjs uninstall` to remove Grudge-managed files.
+
+## What the shrink shows
+
+The headline visual is the shrink: many captured tool responses become the
+small causal world that still reproduces the failure. The repository includes
+a static visual reference for the story; the live viewer animates the same
+transition from the retained `shrink.*` events.
+
+![Shrink visual reference: a captured trace reduced to a three-entry cassette](docs/assets/shrink.svg)
+
+## Architecture
+
+The engine is CLI-first. The recorder emits a typed trace, replay freezes only
+the external world while the policy stays live, the shrinker reduces the
+cassette, deterministic predicate code checks behavior, admission proves that
+the rule discriminates, and the gate turns repeated clean runs into a CI
+decision. The local demo server adds an event stream consumed by the static
+viewer; the viewer never owns pipeline state or verdict logic.
+
+![Grudge pipeline architecture](docs/assets/pipeline.svg)
+
+```text
+agent run → trace → cassette + live policy → minimal cassette
+                                      ↓
+                         predicate → admission proof → statistical gate
+                                      ↓
+                         demo events → local SSE server → static viewer
+```
+
+The full contracts and boundaries are in
+[`docs/architecture.md`](docs/architecture.md).
+
+## How a failure becomes a Scar
+
+Each Scar contains three reviewable artifacts:
+
+1. **Cassette — the frozen world.** An ordered set of task/tool-response
+   entries. Replay serves only cassette responses, with strict matching and
+   single-use entries, while the policy computes its next action from the
+   resulting messages. This keeps replay hermetic without replaying a
+   transcript verbatim. See [`docs/cassette-format.md`](docs/cassette-format.md)
+   and [`docs/why-not-replay.md`](docs/why-not-replay.md).
+2. **Predicate — the never-again rule.** A small readable DSL expresses call
+   shape, ordering, and MVP-lite taint flow. The parser/compiler returns exact
+   trace evidence and a deterministic `PredicateResult`; optional model
+   synthesis can draft text, but deterministic code decides. See
+   [`docs/predicate-dsl.md`](docs/predicate-dsl.md).
+3. **Verdict — proof and gate evidence.** Admission requires witnessed red
+   bad-agent runs, clean successful fixed-agent runs, nonempty benign controls,
+   and fail-closed replay/checker behavior. The statistical gate repeats an
+   admitted Scar and passes only when its Wilson lower bound reaches the
+   threshold. Offline repetitions demonstrate repeatability, not independent
+   statistical samples. See [`docs/statistics.md`](docs/statistics.md) and
+   [`docs/architecture.md`](docs/architecture.md#admission-rules).
+
+## CLI reference
+
+Run `grudge --help` or append `--help` to any command. Every implemented
+command accepts `--json` for one machine-readable document on stdout and
+`--debug` for a traceback on stderr. Expected input/engine failures use exit
+code `2`; a gate passes with `0` and is blocked with `1`.
+
+### Capture
+
+```text
+grudge capture AGENT_MODULE --out PATH [--json] [--debug]
+```
+
+Calls the module's `run_agent` or `run` entry point and writes canonical JSONL
+trace output.
+
+### Shrink
+
+```text
+grudge shrink TRACE --failure RULE --out PATH
+    [--agent AGENT_MODULE] [--json] [--debug]
+```
+
+Reduces a trace-derived cassette while retaining the supplied DSL rule.
+`--failure demo` selects the checked-in hand-verified demo rule;
+`--agent` defaults to `examples.leaky_agent.agent`.
+
+### Admit
+
+```text
+grudge admit CASSETTE --bad AGENT_MODULE --good AGENT_MODULE --out PATH
+    [--id TEXT] [--predicate RULE|demo] [--controls PATH] [--runs INT]
+    [--json] [--debug]
+```
+
+Builds a candidate Scar and admits it only after repeated red/green proof and
+benign controls. `--controls` defaults to
+`examples/leaky_agent/controls`; `--runs` defaults to `3`; `--predicate demo`
+uses the fallback rule.
+
+### Run the gate
+
+```text
+grudge run --scars PATH --agent AGENT_MODULE
+    [--runs INT] [--threshold FLOAT] [--json] [--debug]
+```
+
+Runs one Scar file or every `*.scar.json` in a directory. Defaults come from
+`grudge.config` (`20` runs and threshold `0.80`). The report labels the normal
+path `offline/deterministic`.
+
+### Demo and viewer
+
+```text
+grudge demo [--live] [--guard] [--port INT] [--no-browser] [--runs INT] [--fast]
+    [--json] [--debug]
+grudge viewer [--json] [--debug]
+```
+
+`demo` defaults to the local viewer server on port `8765`; `--no-browser`
+prints the URL instead. `--fast` removes presenter pacing. `--live` is a
+reserved future provider mode and currently reports an error. `viewer` remains
+an explicit roadmap stub; the supported viewer path is `grudge demo`.
+`grudge demo --guard --json` runs the offline two-session proof: it captures a
+real Claude-style hook payload, proposes and accepts the rule, then blocks the
+same data-flow attempt at PreToolUse. The proof uses no network or model call.
+
+### Browse Scars
+
+```text
+grudge scars list [--scars PATH] [--json] [--debug]
+grudge scars show SCAR [--scars PATH] [--json] [--debug]
+grudge scars retire SCAR [--json] [--debug]
+```
+
+`list` and `show` are implemented. `retire` is reserved for the future
+registry and returns an explicit roadmap error.
+
+For a shell pipeline and JSON/error examples, see
+[`docs/demo-guide.md`](docs/demo-guide.md).
+
+## Status
+
+| Area | MVP status | STRETCH status |
+|---|---|---|
+| Typed trace, cassette, predicate, and Scar schemas | Implemented and persisted | — |
+| Recording and redaction | Recorder, decorator, raw SDK boundary, and configurable redaction implemented | MCP and LangGraph adapters are stubs |
+| Replay and shrinking | Hermetic cassette replay, ddmin, content reducers, and deterministic history implemented | Fault locator is a stub |
+| Predicates | Call shape, ordering, and MVP-lite taint flow implemented; outcome AST parses | Outcome checker is a stub |
+| Admission and statistics | Red/green proof, controls, Wilson gate, Rich/Markdown reports implemented | Changed-Scar selector is a stub |
+| CLI and demo | Capture, shrink, admit, run, demo, Guard proof, and Scar list/show implemented | `viewer` and `scars retire` commands are explicit stubs |
+| Static viewer | CDN-free event-driven dashboard with replay, pause, reconnect, and evidence panels implemented | Full Scar browser/registry integration remains a stub/minimal boundary |
+| Ecosystem integrations | Local/offline path needs no external service | SQLite registry, fuzzer, locator, pytest/GitHub integrations, and workflow are deferred |
+
+### Guard tiers and token budgets
+
+| Tier | Agents | Meaning |
+|---|---|---|
+| **Guard** | Claude Code (verified) | Hooks enforce expressible scars before a tool runs. |
+| **Advisory** | Agents that read instruction files | The model receives the rule; compliance is not guaranteed. |
+| **CI only** | Other agents | Check scars afterward with `grudge run` in CI. |
+
+Injected output is bounded: SessionStart 1,200 characters and 8 scars, block
+reason 400 characters, prompt nudge 200 characters, and the managed block 1,000
+characters across at most 12 lines. Token savings are always labeled **est.**
+
+The complete stub/design register is [`docs/roadmap.md`](docs/roadmap.md).
+
+## Benchmark status
+
+The row below is a measured offline CLI run on WSL Ubuntu-D with Python 3.11.17
+using the checked-in vulnerable agent and the command path documented in
+`docs/demo-guide.md`. Wall time includes capture and shrink; cassette bytes are
+the pretty-printed JSON artifact written by `grudge shrink --json`. Repeat on a
+different machine before comparing timings; do not infer measurements from the
+demo narration.
+
+| Workload | Original steps | Minimal steps / entries | Oracle calls | Wall time | Cassette bytes |
+|---|---:|---:|---:|---:|---:|
+| Demo leak (offline, deterministic; WSL Ubuntu-D / Python 3.11.17) | 71 | 23 | 1,254 | 46.357 s | 3,756 |
+
+The implementation already reports shrink statistics (`original_entries`,
+`minimal_entries`, `oracle_calls`, and byte sizes) in `grudge shrink --json`,
+which is the source for the measured row above. The deterministic input helper
+can generate a configurable trace for stress tests and future benchmark runs:
+
+```bash
+python scripts/generate_trace.py --steps 40 --output artifacts/phase12/trace.jsonl
+```
+
+It does not time shrinking or aggregate measurements automatically; benchmark
+rows must be captured from a clean run and recorded with their environment.
+
+## Checks and reproducibility
+
+The default supported runtime is Python 3.14.0, recorded in `.python-version`.
+The package supports Python 3.11 through 3.14, and the lockfile is
+`requirements.lock`. The project Makefile keeps dependencies in a local virtual
+environment:
+
+```bash
+make install
+make test
+make lint
+make typecheck
+make docs-check
+make all
+```
+
+### Clean Linux commands
+
+From a fresh checkout, the shortest reproducible workflow is:
+
+```bash
+git clone https://github.com/harshithKumar12/Grudge.git
+cd Grudge
+python3.14 --version
+make install
+make test
+make demo
+```
+
+`make test` runs the Python suite and the Node package suite when Node.js 18+
+is installed; it remains usable on a Python-only machine. The headless proof
+is useful in CI:
+
+```bash
+.venv/bin/python -m grudge demo --guard --json
+```
+
+The offline path needs no API keys or real personal data. Copy `.env.example`
+only when experimenting with the optional provider boundary; never commit a
+key. Docker remains an optional reproducibility path:
+
+```bash
+docker build -t grudge:latest .
+docker run --rm grudge:latest
+```
+
+## Repository guide
+
+- [Architecture](docs/architecture.md) — contracts and pipeline boundaries.
+- [Documentation index](docs/INDEX.md) — every documentation file and owner phase.
+- [Roadmap](docs/roadmap.md) — every deferred stub and its design notes.
+- [Demo guide](docs/demo-guide.md) — presenter, server, JSON, and shell operation.
+- [Pitch artifacts](pitch/one_liner.md) — one-liner, 90-second script, and slides.
+- [Progress tracker](Progress.md) — canonical phase status.

grudge_cli-0.1.0/README.md

@@ -0,0 +1,292 @@
+# Grudge
+
+**Agents repeat mistakes. Grudge makes each one happen exactly once.**
+
+## The problem
+
+Agent failures are often buried in long, provider-dependent transcripts that are difficult to reproduce. A copied transcript can show what happened, but it cannot show whether the live policy would make the same decision when the world changes. Grudge turns one failure into a small, reviewable regression Scar that can run offline and block the same behavior from returning.
+
+## 30-second quickstart
+
+Use Python 3.14.0 or another interpreter supported by `pyproject.toml`, then run
+the complete offline demo from the repository root:
+
+```bash
+pip install -e . && grudge demo
+```
+
+The command opens the local viewer and plays the five-beat story: capture the
+vulnerable run, shrink its world, synthesize a predicate, prove red-on-bad and
+green-on-fixed admission, then reintroduce the bug and block it. The demo is
+offline and deterministic: it uses checked-in fake tools, scripted policies,
+the checked-in Scar, and the fallback predicate; it does not call a provider or
+the public network. For a headless smoke run, use
+`python -m grudge demo --no-browser --fast --json`. For the two-session
+Claude-style hook proof, use `python -m grudge demo --guard --json`.
+
+### Install the local guard
+
+These commands exercise the checkout's Node package from the repository root;
+they do not resolve a package from the npm registry:
+
+```bash
+npm --prefix packages/grudge run build
+npm --prefix packages/grudge run setup:repo
+npm --prefix packages/grudge run doctor:repo
+```
+
+If `grudge` has been published, the equivalent registry workflow is
+`npx grudge-cli ...`. When working from `packages/grudge`, use `node dist/grudge.mjs`
+and add `--cwd ../..` when the hooks should target the repository root. The
+short package-directory commands are `npm run setup:repo` and
+`npm run doctor:repo`. Do not combine `cd packages/grudge` with the
+root-relative path `packages/grudge/dist/grudge.mjs`, or it resolves to
+`packages/grudge/packages/grudge/dist/grudge.mjs`.
+
+Claude Code is the verified **Guard** tier. Codex, Gemini CLI, GitHub Copilot,
+OpenCode, and Windsurf are **Advisory** integrations; Cursor is unverified and
+the installer writes no Cursor files. See [the integration matrix](docs/integrations.md).
+Use `node packages/grudge/dist/grudge.mjs setup --dry-run` to inspect a plan and
+`node packages/grudge/dist/grudge.mjs uninstall` to remove Grudge-managed files.
+
+## What the shrink shows
+
+The headline visual is the shrink: many captured tool responses become the
+small causal world that still reproduces the failure. The repository includes
+a static visual reference for the story; the live viewer animates the same
+transition from the retained `shrink.*` events.
+
+![Shrink visual reference: a captured trace reduced to a three-entry cassette](docs/assets/shrink.svg)
+
+## Architecture
+
+The engine is CLI-first. The recorder emits a typed trace, replay freezes only
+the external world while the policy stays live, the shrinker reduces the
+cassette, deterministic predicate code checks behavior, admission proves that
+the rule discriminates, and the gate turns repeated clean runs into a CI
+decision. The local demo server adds an event stream consumed by the static
+viewer; the viewer never owns pipeline state or verdict logic.
+
+![Grudge pipeline architecture](docs/assets/pipeline.svg)
+
+```text
+agent run → trace → cassette + live policy → minimal cassette
+                                      ↓
+                         predicate → admission proof → statistical gate
+                                      ↓
+                         demo events → local SSE server → static viewer
+```
+
+The full contracts and boundaries are in
+[`docs/architecture.md`](docs/architecture.md).
+
+## How a failure becomes a Scar
+
+Each Scar contains three reviewable artifacts:
+
+1. **Cassette — the frozen world.** An ordered set of task/tool-response
+   entries. Replay serves only cassette responses, with strict matching and
+   single-use entries, while the policy computes its next action from the
+   resulting messages. This keeps replay hermetic without replaying a
+   transcript verbatim. See [`docs/cassette-format.md`](docs/cassette-format.md)
+   and [`docs/why-not-replay.md`](docs/why-not-replay.md).
+2. **Predicate — the never-again rule.** A small readable DSL expresses call
+   shape, ordering, and MVP-lite taint flow. The parser/compiler returns exact
+   trace evidence and a deterministic `PredicateResult`; optional model
+   synthesis can draft text, but deterministic code decides. See
+   [`docs/predicate-dsl.md`](docs/predicate-dsl.md).
+3. **Verdict — proof and gate evidence.** Admission requires witnessed red
+   bad-agent runs, clean successful fixed-agent runs, nonempty benign controls,
+   and fail-closed replay/checker behavior. The statistical gate repeats an
+   admitted Scar and passes only when its Wilson lower bound reaches the
+   threshold. Offline repetitions demonstrate repeatability, not independent
+   statistical samples. See [`docs/statistics.md`](docs/statistics.md) and
+   [`docs/architecture.md`](docs/architecture.md#admission-rules).
+
+## CLI reference
+
+Run `grudge --help` or append `--help` to any command. Every implemented
+command accepts `--json` for one machine-readable document on stdout and
+`--debug` for a traceback on stderr. Expected input/engine failures use exit
+code `2`; a gate passes with `0` and is blocked with `1`.
+
+### Capture
+
+```text
+grudge capture AGENT_MODULE --out PATH [--json] [--debug]
+```
+
+Calls the module's `run_agent` or `run` entry point and writes canonical JSONL
+trace output.
+
+### Shrink
+
+```text
+grudge shrink TRACE --failure RULE --out PATH
+    [--agent AGENT_MODULE] [--json] [--debug]
+```
+
+Reduces a trace-derived cassette while retaining the supplied DSL rule.
+`--failure demo` selects the checked-in hand-verified demo rule;
+`--agent` defaults to `examples.leaky_agent.agent`.
+
+### Admit
+
+```text
+grudge admit CASSETTE --bad AGENT_MODULE --good AGENT_MODULE --out PATH
+    [--id TEXT] [--predicate RULE|demo] [--controls PATH] [--runs INT]
+    [--json] [--debug]
+```
+
+Builds a candidate Scar and admits it only after repeated red/green proof and
+benign controls. `--controls` defaults to
+`examples/leaky_agent/controls`; `--runs` defaults to `3`; `--predicate demo`
+uses the fallback rule.
+
+### Run the gate
+
+```text
+grudge run --scars PATH --agent AGENT_MODULE
+    [--runs INT] [--threshold FLOAT] [--json] [--debug]
+```
+
+Runs one Scar file or every `*.scar.json` in a directory. Defaults come from
+`grudge.config` (`20` runs and threshold `0.80`). The report labels the normal
+path `offline/deterministic`.
+
+### Demo and viewer
+
+```text
+grudge demo [--live] [--guard] [--port INT] [--no-browser] [--runs INT] [--fast]
+    [--json] [--debug]
+grudge viewer [--json] [--debug]
+```
+
+`demo` defaults to the local viewer server on port `8765`; `--no-browser`
+prints the URL instead. `--fast` removes presenter pacing. `--live` is a
+reserved future provider mode and currently reports an error. `viewer` remains
+an explicit roadmap stub; the supported viewer path is `grudge demo`.
+`grudge demo --guard --json` runs the offline two-session proof: it captures a
+real Claude-style hook payload, proposes and accepts the rule, then blocks the
+same data-flow attempt at PreToolUse. The proof uses no network or model call.
+
+### Browse Scars
+
+```text
+grudge scars list [--scars PATH] [--json] [--debug]
+grudge scars show SCAR [--scars PATH] [--json] [--debug]
+grudge scars retire SCAR [--json] [--debug]
+```
+
+`list` and `show` are implemented. `retire` is reserved for the future
+registry and returns an explicit roadmap error.
+
+For a shell pipeline and JSON/error examples, see
+[`docs/demo-guide.md`](docs/demo-guide.md).
+
+## Status
+
+| Area | MVP status | STRETCH status |
+|---|---|---|
+| Typed trace, cassette, predicate, and Scar schemas | Implemented and persisted | — |
+| Recording and redaction | Recorder, decorator, raw SDK boundary, and configurable redaction implemented | MCP and LangGraph adapters are stubs |
+| Replay and shrinking | Hermetic cassette replay, ddmin, content reducers, and deterministic history implemented | Fault locator is a stub |
+| Predicates | Call shape, ordering, and MVP-lite taint flow implemented; outcome AST parses | Outcome checker is a stub |
+| Admission and statistics | Red/green proof, controls, Wilson gate, Rich/Markdown reports implemented | Changed-Scar selector is a stub |
+| CLI and demo | Capture, shrink, admit, run, demo, Guard proof, and Scar list/show implemented | `viewer` and `scars retire` commands are explicit stubs |
+| Static viewer | CDN-free event-driven dashboard with replay, pause, reconnect, and evidence panels implemented | Full Scar browser/registry integration remains a stub/minimal boundary |
+| Ecosystem integrations | Local/offline path needs no external service | SQLite registry, fuzzer, locator, pytest/GitHub integrations, and workflow are deferred |
+
+### Guard tiers and token budgets
+
+| Tier | Agents | Meaning |
+|---|---|---|
+| **Guard** | Claude Code (verified) | Hooks enforce expressible scars before a tool runs. |
+| **Advisory** | Agents that read instruction files | The model receives the rule; compliance is not guaranteed. |
+| **CI only** | Other agents | Check scars afterward with `grudge run` in CI. |
+
+Injected output is bounded: SessionStart 1,200 characters and 8 scars, block
+reason 400 characters, prompt nudge 200 characters, and the managed block 1,000
+characters across at most 12 lines. Token savings are always labeled **est.**
+
+The complete stub/design register is [`docs/roadmap.md`](docs/roadmap.md).
+
+## Benchmark status
+
+The row below is a measured offline CLI run on WSL Ubuntu-D with Python 3.11.17
+using the checked-in vulnerable agent and the command path documented in
+`docs/demo-guide.md`. Wall time includes capture and shrink; cassette bytes are
+the pretty-printed JSON artifact written by `grudge shrink --json`. Repeat on a
+different machine before comparing timings; do not infer measurements from the
+demo narration.
+
+| Workload | Original steps | Minimal steps / entries | Oracle calls | Wall time | Cassette bytes |
+|---|---:|---:|---:|---:|---:|
+| Demo leak (offline, deterministic; WSL Ubuntu-D / Python 3.11.17) | 71 | 23 | 1,254 | 46.357 s | 3,756 |
+
+The implementation already reports shrink statistics (`original_entries`,
+`minimal_entries`, `oracle_calls`, and byte sizes) in `grudge shrink --json`,
+which is the source for the measured row above. The deterministic input helper
+can generate a configurable trace for stress tests and future benchmark runs:
+
+```bash
+python scripts/generate_trace.py --steps 40 --output artifacts/phase12/trace.jsonl
+```
+
+It does not time shrinking or aggregate measurements automatically; benchmark
+rows must be captured from a clean run and recorded with their environment.
+
+## Checks and reproducibility
+
+The default supported runtime is Python 3.14.0, recorded in `.python-version`.
+The package supports Python 3.11 through 3.14, and the lockfile is
+`requirements.lock`. The project Makefile keeps dependencies in a local virtual
+environment:
+
+```bash
+make install
+make test
+make lint
+make typecheck
+make docs-check
+make all
+```
+
+### Clean Linux commands
+
+From a fresh checkout, the shortest reproducible workflow is:
+
+```bash
+git clone https://github.com/harshithKumar12/Grudge.git
+cd Grudge
+python3.14 --version
+make install
+make test
+make demo
+```
+
+`make test` runs the Python suite and the Node package suite when Node.js 18+
+is installed; it remains usable on a Python-only machine. The headless proof
+is useful in CI:
+
+```bash
+.venv/bin/python -m grudge demo --guard --json
+```
+
+The offline path needs no API keys or real personal data. Copy `.env.example`
+only when experimenting with the optional provider boundary; never commit a
+key. Docker remains an optional reproducibility path:
+
+```bash
+docker build -t grudge:latest .
+docker run --rm grudge:latest
+```
+
+## Repository guide
+
+- [Architecture](docs/architecture.md) — contracts and pipeline boundaries.
+- [Documentation index](docs/INDEX.md) — every documentation file and owner phase.
+- [Roadmap](docs/roadmap.md) — every deferred stub and its design notes.
+- [Demo guide](docs/demo-guide.md) — presenter, server, JSON, and shell operation.
+- [Pitch artifacts](pitch/one_liner.md) — one-liner, 90-second script, and slides.
+- [Progress tracker](Progress.md) — canonical phase status.

grudge_cli-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Example agents used by later Grudge phases."""

grudge_cli-0.1.0/examples/leaky_agent/__init__.py

@@ -0,0 +1 @@
+"""Prompt-injection example reserved for Phase 2."""