keelyard 1.0.0__tar.gz

keelyard-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,27 @@
+name: Bug report
+description: Something in keelyard does not work as documented
+labels: ["bug"]
+body:
+  - type: dropdown
+    id: agent
+    attributes:
+      label: Agent
+      options: [Claude Code, Codex, OpenCode, CLI only, Other]
+    validations: { required: true }
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: "`keelyard --version`, the agent's version, OS"
+    validations: { required: true }
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what did you expect?
+    validations: { required: true }
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant lines from .keelyard/hook.log
+      description: Remove secrets and private paths first.
+      render: text

keelyard-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issue
+    url: https://github.com/akobirjontulqinovfuture/keelyard/security/advisories/new
+    about: Please report vulnerabilities privately.

keelyard-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature or adapter request
+description: A new filter, agent adapter, proof check or benchmark
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What costs you tokens, time or trust today?
+    validations: { required: true }
+  - type: textarea
+    id: idea
+    attributes:
+      label: Proposed behaviour
+  - type: textarea
+    id: sample
+    attributes:
+      label: A real sample (command output, transcript snippet), with secrets removed
+      render: text

keelyard-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## What and why
+
+## How I verified it
+- [ ] `pytest -q` and `ruff check src tests` pass
+- [ ] New behaviour has a test (hooks: never crash the agent; filters: keep every failure/error line)
+- [ ] Any number in docs comes from `keelyard bench` or a script in `bench/`, with machine and date
+- [ ] No secrets, personal paths or copied third-party code (see NOTICE)

keelyard-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: ci
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests bench
+      - run: pytest -q
+      - run: keelyard selftest
+  clean-env:
+    # fresh venv + fresh HOME + non-editable install: init, doctor, selftest, uninstall leaves no trace
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: bash ci/clean_env.sh
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install mkdocs-material
+      - run: mkdocs build --strict

keelyard-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,14 @@
+name: docs
+on: workflow_dispatch
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

keelyard-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+# Publishes to PyPI when a GitHub release is published, via Trusted Publishing (OIDC, no token stored).
+# One-time setup on pypi.org: pending publisher = owner akobirjontulqinovfuture, repo keelyard,
+# workflow "publish.yml", environment "pypi".
+name: publish
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - run: python -m pip install build twine && python -m build && twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with: {name: dist, path: dist/}
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: {name: dist, path: dist/}
+      - uses: pypa/gh-action-pypi-publish@release/v1

keelyard-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+*.egg-info/
+*.env
+.env*
+.keelyard/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+site

keelyard-1.0.0/.gitleaks.toml

@@ -0,0 +1,7 @@
+# Test fixtures use fake, well-known-format keys to check redaction. They are not secrets.
+[extend]
+useDefault = true
+
+[allowlist]
+description = "fake keys in tests"
+paths = ['''tests/test_redact\.py''', '''tests/test_memory\.py''']

keelyard-1.0.0/AGENTS-install.md

@@ -0,0 +1,46 @@
+# Installing keelyard (instructions for coding agents)
+
+This page is for a coding agent helping a user who has explicitly asked to install keelyard
+(for example "install https://github.com/akobirjontulqinovfuture/keelyard"). If the user did not ask, do not install it.
+
+Before running anything, show the user the commands below and the files they change, and wait for their
+confirmation. `init --global` edits user-level config for every project, so it needs a clear yes.
+
+1. Install the CLI (Python 3.11+ and git required):
+
+   ```sh
+   pipx install git+https://github.com/akobirjontulqinovfuture/keelyard
+   ```
+
+   No pipx: `python -m pip install --user git+https://github.com/akobirjontulqinovfuture/keelyard`, and make sure the
+   scripts folder is on PATH (`keelyard --version` must work).
+
+2. Wire every agent for every project of this user:
+
+   ```sh
+   keelyard init --global
+   ```
+
+   | agent | files changed |
+   |---|---|
+   | Claude Code | `~/.claude/settings.json` (hooks), `~/.claude.json` (MCP server), `~/.claude/CLAUDE.md` (rules block), `~/.claude/skills/keelyard`, `~/.claude/commands/keelyard` |
+   | Codex | `~/.codex/config.toml` (`[mcp_servers.keelyard]` between `# keelyard:start/end`), `~/.codex/hooks.json`, `~/.codex/AGENTS.md` |
+   | OpenCode | `~/.config/opencode/opencode.json` (MCP), `~/.config/opencode/plugin/keelyard.js`, `~/.config/opencode/AGENTS.md`, `command/keelyard-*.md` |
+
+   Existing settings are merged, not replaced. The first time a file is changed, the original is kept as
+   `<file>.keelyard-backup`. Running it again is safe.
+
+3. Verify:
+
+   ```sh
+   keelyard doctor --json
+   ```
+
+   Expect `"ok": true` and one `"section": "global"` check per agent with `"state": "ok"`. Report any `bad` row's
+   `detail` to the user; it says how to fix it.
+
+4. Let the user know to restart their agent. Each git project sets itself up on its first session
+   (`.keelyard/config.toml` plus a first snapshot). Folders that are not git repositories are left alone.
+   Codex asks once to trust new hooks (`/hooks`).
+
+Remove: `keelyard uninstall --global` removes only keelyard's entries and leaves everything else as it was.

keelyard-1.0.0/BENCHMARKS.md

@@ -0,0 +1,184 @@
+
+## Whole-session tokens, keelyard lean vs none (Oct 17, 2026)
+
+Real `opencode run` sessions (OpenCode 1.19.0, free `opencode/big-pickle`, $0) on six task types, each in a fresh
+repo; hidden checks decide success. Total = input + cache read + cache write + output + reasoning, keelyard's brief
+and hints included; every attempt counts. Target: ≥70% saving per task with success not lower than baseline
+(`python bench/session/report.py bench/session/runs_v4.jsonl` exits 1 otherwise). v4 = commit 2b5e877.
+
+| task | runs (base/lean) | baseline tokens (mean) | lean tokens (mean) | saving | correct base | correct lean | gate |
+|---|---|---:|---:|---:|---:|---:|---|
+| edit-heavy | 8/8 | 47,958 | 10,626 | 78% | 88% | 100% | pass |
+| log-heavy | 3/3 | 57,614 | 10,373 | 82% | 100% | 100% | pass |
+| qa-large | 3/3 | 20,863 | 3,053 | 85% | 100% | 100% | pass |
+| read-heavy-large | 3/3 | 48,533 | 10,595 | 78% | 100% | 100% | pass |
+| small-feature | 3/3 | 51,916 | 11,965 | 77% | 100% | 100% | pass |
+| tiny-fix | 3/3 | 40,642 | 6,134 | 85% | 100% | 100% | pass |
+| **all (sum of means)** | | 267,525 | 52,745 | 80% | | | |
+
+edit-heavy fix (v3 → v4): in v3 one of 8 lean runs made 17 per-file read+edit calls (71k tokens) and missed a use
+(62% saving, 88% correct). The lean brief now carries a rename hint for "rename X to Y" tasks: every tracked file
+holding X and one `perl -pi` command over them; the lean prompt asks for one bulk command. All 8 v4 lean runs used it
+(2–4 calls, 7–16k tokens). v4 re-ran the other tasks with 3 reps each to check for regressions (v3: 5 reps, see
+`runs_v3.jsonl`). One model, one agent, 3–8 reps per task: indicative, not general. Claude Code and Codex are not
+measured here.
+
+## Terse-output rule, measured on local models (Oct 17, 2026)
+
+`python bench/terse.py --models qwen2.5-0.5b,llama3.2-1b,qwen-coder-1.5b --seeds 1,2` (Ollama, Q4, temperature 0.3):
+32 coding prompts x 2 seeds = 64 answers per model and rule. Tokens are Ollama's own counts, input
+(`prompt_eval_count`, so the rule's cost is included) + output (`eval_count`). "Facts" = the answer contains
+what the prompt needs (identifier, fix, error name). Raw numbers: `bench/terse.json`. $0, no paid calls.
+
+| rule | total tokens (3 models) | facts (of 192) |
+|---|---:|---:|
+| old "Be terse: no preamble, no restating the question, no summary of what you are about to do." | 24,053 | 142 |
+| previous rule ("Reply with results only: ... exact and complete.", ~33 tokens) | 31,870 | 150 |
+| **shipped: "Be terse: no preamble or recap. Keep code exact."** (~12 tokens) | **23,428 (−2.6% vs old)** | **155** |
+| "Be terse. Keep code and facts." | 27,310 | 158 |
+| "Be terse: answer first, no preamble or recap; keep code and facts complete." | 28,827 | 155 |
+
+Per model (total / facts): qwen2.5-0.5b old 9,444/44, shipped 8,271/45; llama3.2-1b old 6,884/45,
+previous 10,799/52, shipped 7,022/49; qwen-coder-1.5b old 7,725/53, previous 12,342/51, shipped 8,135/61.
+
+- The shipped rule beats the old line on total tokens and the previous rule on facts summed over three models,
+  but not on every model: on llama3.2-1b it uses 2% more tokens than the old line and keeps fewer facts than the
+  previous rule. The token margin over the old line is small. Not measured with Claude or GPT models.
+- Lossless JSON compaction: pretty `gh search repos --json` output 2,121 → 1,236 tokens (−42%), decoded back
+  exactly (`bench/mechanisms.py`). An already-minified GitHub issue list shrank only 3%.
+- The repeated-failure hint (about 40 tokens, only when it fires) was not measured for savings.
+
+## Token-saving mechanisms, measured locally (Oct 16, 2026)
+
+`python bench/mechanisms.py` (no model, no network, $0). Tokens are `chars / 4`. Fixtures: this repo,
+the installed `httpx` package source, and the two-file `examples/arena/discount/repo`. The keelyard row shifts a little with every commit (it measures itself). Each row compares
+keelyard with what an agent does without it, and checks the agent still gets what it needs.
+Raw numbers: [`bench/mechanisms.json`](https://github.com/akobirjontulqinovfuture/keelyard/blob/main/bench/mechanisms.json).
+
+| mechanism | baseline | keelyard | keelyard repo | httpx | discount (2 files) | correctness check |
+|---|---|---|---|---|---|---|
+| 1 find code | grep the name, read the whole defining file | ranked `find_symbol` page + outline + the definition's lines + `related` | 16,969 → 3,691 (−78%) | 54,731 → 16,717 (−69%) | 107 → 108 (**+1%**) | the definition is in the slice read |
+| 2 re-reads | read, re-read, read after a 1-line edit (5 largest files) | full, "unchanged" notice, diff | 127,392 → 43,289 (−66%) | 146,937 → 49,689 (−66%) | 456 → 387 (−15%) | diff applied to the first read = the edited file; `force=true` returns all of it |
+| 3 logs, real `pytest -v` | raw output | `filter_output` | 1,233 → 9 (all passed) | – | 401 → 149 (−63%, 2 failures) | every error/failure/count line kept; failing test ids kept |
+| 3 logs, corpus (10 tools, pytest padded with 300 passes) | raw | filtered | 7,965 → 1,502 (−81%) | | | same |
+| 4 paging | every match in one response | first page of 20 + `remaining`/`next_offset` | 8,849 → 416 (−95%) | 7,007 → 324 (−95%) | 99 → 99 (0%) | walking every page returns every result in order |
+| 5 work state | re-read the 3 changed files after a compaction (modeled) | `work_state` render | 26,574 → 241 | 33,055 → 182 | 177 → 111 | every ref resolves to a real file line or command |
+| 6 tool schemas per request | `core` (14 tools) | `lazy` (6 tools) | 2,319 → 927 (−60%) | | | every hidden core tool is found by `tool_search` |
+
+What this does not show:
+- Row 1 on a tiny repo is **one token worse**: when the file is smaller than an outline, just read it.
+- Row 4 saves only when the answer is on the first page; reading every page costs slightly more than one dump.
+- Row 5's baseline is a model of what an agent re-reads, not a measured session.
+- Row 6: each on-demand tool use (search + call) adds about 309 tokens that stay in context, so `lazy` is
+  smaller only while a session uses fewer than 4 distinct hidden tools. The proof workflow alone uses about 4,
+  which is why `core` stays the default and `lazy` is opt-in.
+- None of this was measured in a live agent session.
+
+## Real agent run: OpenCode 2.0.22 on Windows 11 (Oct 15, 2026)
+
+One run each, same task and same free model (`opencode/big-pickle`, cost reported by OpenCode: $0).
+Task: fix a SAVE10 coupon, reject unknown coupons, floor `inventory.remove` at zero (3 failing of 66 tests).
+Raw data: [`bench/real/`](bench/real/); numbers produced by `bench/real/summarize.py` from `opencode session export`.
+
+| | baseline (no keelyard) | with keelyard |
+|---|---|---|
+| tests after run | 66/66 pass | 66/66 pass |
+| model calls | 5 | 6 |
+| input tokens, uncached | 16,436 | 13,654 |
+| input tokens, cache read | 28,864 | 68,544 |
+| input tokens, total | 45,300 | 82,198 |
+| output + reasoning | 897 | 1,568 |
+| wall time | 65 s | 122 s |
+| proof | none | proven, 4 requirements with evidence |
+
+Honest reading: on this small task keelyard **cost more tokens** (+81% total input), not fewer.
+The main causes seen in the export: OpenCode 2 "code mode" injects an ~8.9k-char catalog for keelyard's
+13 MCP tools, and the agent spent one call (19.7k chars) searching that catalog. Test output itself was
+smaller with keelyard (`proof_run_tests`: 2,967 chars vs 7,008 + 5,789 raw `pytest -v` in the baseline),
+but the shell-output filter did not fire because in code mode the agent never called the shell tool directly.
+The 56k→6k savings measured earlier apply to noisy command output, which this task did not produce.
+Rewind was verified on the same project: `rewind to 1` → 3 failed; `rewind to 2` → 66 passed
+([screenshot](docs/img/real/rewind.svg)). Status/proof: [screenshot](docs/img/real/status.svg).
+
+### After the lean-mode fix (commit f93dbaa), same PC, same free model, n=1 per row
+
+keelyard no longer puts an MCP tool catalog into OpenCode's context, counts the agent's own shell test runs as
+proof, and filters shell output. Data: `bench/real/opencode_bigpickle_lean.json`, `opencode_bigpickle_noisy.json`.
+
+| task | run | tests after | model calls | input total (incl. cache) | input uncached | tool output chars |
+|---|---|---|---|---|---|---|
+| shop (66 tests) | baseline | 66/66 | 5 | 44,075 | 6,571 | 14,502 |
+| shop (66 tests) | keelyard before fix | 66/66 | 6 | 82,198 | 13,654 | 26,746 |
+| shop (66 tests) | **keelyard lean** | 66/66, proven | 5 | **37,493 (−15%)** | 4,021 | 2,806 (−81%) |
+| noisy shop (1,566 tests, `pytest -v`) | baseline | 1566/1566 | 6 | 87,168 | 18,496 | 54,407 |
+| noisy shop (1,566 tests, `pytest -v`) | **keelyard lean** | 1566/1566, proven | 5 | **37,257 (2.3× fewer)** | 7,049 (2.6× fewer) | 2,854 (19× fewer) |
+
+What limits the ratio: OpenCode's own system prompt and tool definitions are resent on every model call
+(about 6k tokens per call here), so five calls cost ~30k tokens before any project content. keelyard cuts
+what it controls (tool output 19×, e.g. `pytest -v` 12,849 → 279 tokens) but cannot reach 10× on whole-session
+tokens for short tasks. The gap grows with longer sessions and noisier output.
+
+## Presets, measured on OpenCode 2
+
+Windows 11, OpenCode 2.0.22, free `opencode/big-pickle` ($0), same task text, all runs ended with every test passing
+and (keelyard runs) proof "proven". Session totals from `opencode session export`; raw summaries in
+`bench/real/r6/summary.json` and `bench/real/r7/summary.json`. One run per row, two baseline runs per task.
+
+| task | run | model calls | input incl. cache | uncached | output+reasoning | tool output chars |
+|---|---|---|---|---|---|---|
+| small (66 tests) | baseline, run A | 5 | 46,916 | 11,076 | 1,217 | 14,389 |
+| small (66 tests) | baseline, run B | 5 | 43,849 | 6,921 | 815 | 14,512 |
+| small (66 tests) | keelyard balanced | 7 | 51,652 | 9,801 | 1,162 | 2,502 |
+| small (66 tests) | keelyard lean (7 tools off) | 4 | 11,851 | 3,723 | 493 | 2,654 |
+| small (66 tests) | **keelyard lean (final, 9 tools off)** | 5 | **12,132** | 2,660 | 494 | 2,654 |
+| noisy (1,566 tests, `pytest -v`) | baseline, run A | 8 | 101,528 | 33,122 | 1,270 | 54,887 |
+| noisy (1,566 tests, `pytest -v`) | baseline, run B | 5 | 93,397 | 18,581 | 887 | 54,795 |
+| noisy (1,566 tests, `pytest -v`) | keelyard balanced | 4 | 31,211 | 8,171 | 948 | 3,074 |
+| noisy (1,566 tests, `pytest -v`) | keelyard lean (7 tools off) | 6 | 16,769 | 4,337 | 864 | 2,854 |
+| noisy (1,566 tests, `pytest -v`) | **keelyard lean (final, 9 tools off)** | 4 | **9,995** | 1,867 | 465 | 2,570 |
+
+Ratios against the mean of the two baselines: noisy task **9.7× fewer** input tokens (97,463 → 9,995),
+small task **3.7× fewer** (45,383 → 12,132). Balanced mode on the small task was *above* baseline in this run
+(7 model calls); the session-to-session spread of the same setup is large, so treat single runs as indicative.
+Where the savings come from: the lean OpenCode agent's first request is ~1.5k tokens instead of ~5.5k
+(prompt and tool list), and `pytest -v` output reaches the model as ~300 tokens instead of ~13k.
+
+### Lean preset v2, repeated runs (Oct 15, 2026)
+
+`keelyard init --preset lean` now also puts small project files and the pre-edit test result into the brief and
+reruns the tests after each edit (result appended to the edit's output), so the agent needs no read or "before"
+test calls. Installed through the real `keelyard init --agent opencode --preset lean` on the PC. Same task, free
+`opencode/big-pickle`, $0. Raw data: `bench/real/r6`–`r9/summary.json`.
+
+| task | setup | runs | input tokens incl. cache, per run | mean | model calls |
+|---|---|---|---|---|---|
+| small (66 tests) | baseline | 5 | 46,916 · 43,849 · 43,946 · 43,964 · 68,450 | 49,425 | 5–9 |
+| small (66 tests) | **lean v2** | 3 | 7,884 · 8,950 · 7,973 | **8,269** | 3 |
+| noisy (1,566 tests) | baseline | 5 | 101,528 · 93,397 · 139,837 · 94,923 · 129,229 | 111,783 | 5–11 |
+| noisy (1,566 tests) | **lean v2** | 3 | 8,283 · 7,079 · 8,208 | **7,857** | 3 |
+
+Mean ratio: **noisy 14.2× fewer, small 6.0× fewer** input tokens (cached + uncached together). Every counted run ended with all tests
+passing; every lean run has proof "proven". Two lean runs from an earlier 12-way parallel batch (r8) are not
+counted: OpenCode crashed at startup ("Standalone server exited before reporting readiness") before the agent
+did anything.
+
+Split by cache (same runs, means; from the same `summary.json` files):
+
+| task | | baseline mean | lean v2 mean | ratio |
+|---|---|---|---|---|
+| small | input, uncached | 11,189 | 2,509 | 4.5× |
+| small | input, cache read | 38,236 | 5,760 | 6.6× |
+| noisy | input, uncached | 28,354 | 2,983 | 9.5× |
+| noisy | input, cache read | 83,428 | 4,874 | 17.1× |
+
+Read these numbers with three limits in mind:
+- **No cost claim.** The model was free (`opencode/big-pickle`, $0 reported). On a paid model, cache reads are
+  billed far below uncached input, so the saving in money is closer to the uncached ratio than to the total.
+- **Lean turns tools off.** The lean OpenCode build agent disables 9 built-in tools and keelyard's MCP tool list.
+  That is a large part of the saving, and it means the agent can do less (see docs/guide/presets.md).
+- **Small n, one task family, one agent.** 5 baseline and 3 lean runs per task, OpenCode only. Claude Code and
+  Codex were not measured this way.
+
+The small task does not reach 10×: three model calls (edit, the test run the task text asks for,
+final reply) at ~2.2–3k tokens each are the floor we could reach; the remaining per-call cost is OpenCode's
+tool definitions plus the brief.

keelyard-1.0.0/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+## 1.0.0 (Oct 28, 2026, first PyPI release)
+
+First stable release.
+- Published to PyPI as `keelyard` (`pip install keelyard`) by `.github/workflows/publish.yml`, using PyPI
+  Trusted Publishing (no API token stored in the repo)
+- Timeline browser: `g` / `G` jump to the first / last step (#9)
+- New `mypy` filter: every diagnostic line is kept whole, so the trailing `[error-code]` is no longer clipped;
+  real mypy and pyright output added to the filter corpus with a test (#1)
+- README: PyPI install, "without vs with keelyard" table, per-agent wiring table; ROADMAP.md
+- Version 1.0.0; no longer marked alpha (README badge, PyPI classifier `Production/Stable`)
+- Install docs rewritten (README, `AGENTS-install.md`, `llms.txt`): human instructions first, then a labeled note
+  for AI coding agents to install only when the user explicitly asked, show the commands and get confirmation.
+  Removed the wording that told agents to run the install without the user typing it
+- README: "What keelyard changes on your machine" + uninstall steps; SECURITY.md: reporting process and trust
+  properties; `requirements-lock.txt` (pinned, pip-audit clean)
+- Benchmark numbers unchanged and still small-sample (5 baseline vs 3 lean runs); see BENCHMARKS.md
+
+## 0.1.0 (pre-release)
+
+### Lean defaults made permanent (Oct 17, 2026)
+- Every install path ends on the lean defaults the session bench measured (~80% saving): `init`, `install <agent>`
+  (was balanced; now `--preset`, default lean), `init --global` (now adds OpenCode's lean build agent and Claude
+  Code's lean env at user level, taken back by `uninstall --global`), global first-session setup (lean config)
+- Upgrades: on SessionStart, a lean (or pre-preset) project whose config still has the old default lines gets the
+  lean values; values set by hand are kept
+- `keelyard doctor` warns when lean settings are overridden (project config or user-level agent config)
+- `tests/test_lean_defaults.py`: fails on drift (prompt length, denied tools, terse rule, brief size, filter on,
+  lean config, install/global/upgrade paths) - this is the per-PR static token budget check, run in CI
+- Lean brief: rename hint (every file + one `perl -pi` command); edit-heavy now 78% saving, 100% correct
+- TODO: scheduled weekly/manual session-bench workflow (2 reps/task, free model, fail <70% or correctness <
+  baseline); per-session token recording (OpenCode db, Claude Code/Codex logs) with `usage`/`doctor` warning under
+  target; Codex has no lean agent-config equivalent yet; docs page for these guarantees
+
+### Ideas from popular agent tools, rebuilt from scratch (Oct 16, 2026)
+- Terse-output rule in every preset (CLAUDE.md, AGENTS.md); `--no-terse` / `KEELYARD_TERSE=0` to opt out;
+  `bench/terse.py` measures it on a local model. Rule shortened to ~12 tokens after a 3-model, 32-prompt x 2-seed
+  comparison (fewer total tokens than the old line, more facts than the previous rule)
+- Lossless JSON compaction in the output filters
+- One hint when the same test failure returns after a code change (hooks, auto-test, `proof_run_tests`)
+- Test: the session brief is byte-stable (prompt cache)
+- README credits inspirations; survey of 57 repos in `docs/research/ideas.md`
+
+### Token-saving mechanisms, each with a safeguard (Oct 16, 2026)
+- Find code: ranked `find_symbol` (exact names and source first), `refs=true` call sites, `outline(related=true)`
+  and `keelyard code related FILE` (imports, importers, tests); `keelyard code find --refs --offset --limit`
+- Paged results: `find_symbol` and `memory_search` return `total`, `remaining` and `next_offset`; nothing is cut silently
+- Re-reads: an "unchanged" notice is never sent when the file itself is smaller; diff exactness and `force=true` tested
+- Log compaction: the `keelyard run` footer shows the exit code and how many lines were collapsed; `go test -v`
+  failure messages (printed before `--- FAIL`) are now kept; the corpus test checks counts and stack frames
+- Work state: `work_state` MCP tool and `keelyard state` (decisions, open questions, changed files, requirements);
+  every decision needs a validated ref and stale refs are flagged; included in the brief after compaction
+- `[mcp].tools = "lazy"`: 6 schemas up front plus `tool_search`/`tool_call`; falls back to `core` if not smaller
+- `bench/mechanisms.py` measures all six on three fixture repos (see BENCHMARKS); `python -m keelyard` works
+
+### Trust: proof and rewind (Oct 16, 2026)
+- Proof is bound to a content hash of the worktree: any edit after the last passing test run reopens it,
+  even one made without a hook firing
+- Evidence levels shown separately: test-verified / command-succeeded / agent-claimed (`status`, `proof`, `--json`)
+- Proof bundles are signed (HMAC, key in the user data dir, mode 600); a hand-edited bundle is never proven.
+  Bundles written by older versions have no signature and count as edited: run `keelyard proof reset`
+- Test weakening keeps the proof open: deleted test files, fewer tests or assertions, new skip/xfail/only,
+  test config changed or added, fewer tests run. `keelyard proof accept-tests "<why>"` acknowledges a real
+  refactor, recorded as agent-claimed and bound to those exact files
+- The gate is never shown green when no Stop hook is wired or no agent ever called keelyard (`unhooked`/`unverified`);
+  doctor shows it too
+- Proof writes are locked (parallel hooks and sessions); tested with 12 processes
+- Rewind copies files snapshots cannot hold (ignored, secret, too big) aside before overwriting or deleting them;
+  an interrupted rewind is detected and `keelyard rewind recover` restores the state from just before it
+- Secrets (`.env`, keys, credentials files, ...) are excluded from snapshots by default (`[rewind].include_secrets`,
+  `[rewind].exclude`); a file that becomes excluded is dropped from the timeline index
+- Filter corpus of real logs; pytest keeps the warnings summary, cargo keeps warning blocks
+- Dependencies capped at the next major version; new CI job: clean venv + clean HOME install, init, doctor,
+  selftest, uninstall leaves the project unchanged, on Linux, macOS and Windows
+- Docs: "What keelyard guarantees and what it doesn't" with a per-agent capability table; shorter README;
+  BENCHMARKS splits cached and uncached input and states the free-model and tools-off limits
+
+### Audit fixes, round 2 (Oct 16, 2026)
+- Codex: opt-in `--codex-project-mcp` on `init` and `install codex` writes the MCP server to `.codex/config.toml`
+- `--json` works before or after the action in every group command (`keelyard proof --json status`)
+- No trailing spaces in human output; error hints are not hard-wrapped
+- `rewind` and the timeline browser name your files and count agent setup files (`a.py (+5 agent setup)`)
+- memory and usage read OpenCode's `opencode.db` (OpenCode 1.x+/2.x keep sessions there, not in `storage/`);
+  read-only, only the session/message/part tables; messages left over from the JSON-to-SQLite migration count once
+- swarm: `swarm plan --json > tasks.json` feeds `swarm run tasks.json` (it failed before); an error file from
+  `plan` is refused with its hint; a missing API key is reported before any call; HTTP 401/402/404/429 and
+  unreachable servers get one-line explanations with a free-model hint; exit 3 when every call failed;
+  `--model` is honored in cooperative mode (it was ignored)
+- arena: per-contender summary and progress in the terminal; `files_changed` no longer counts the caches
+  the check writes; no matplotlib font warnings
+- timeline browser: tests drive it headless; a cut diff says so and how to see all of it
+
+### Audit fixes (Oct 16, 2026)
+- `keelyard uninstall <agent>` now restores config files byte for byte (formatting included), deletes the `{}` files
+  and empty folders keelyard created, and leaves files alone if you edited them after install
+- `keelyard run` never makes output bigger: when filtering saves less than its own footer, the raw output is returned
+- pytest output drops frames from site-packages and the standard library and shortens `=====` banners
+- A failing test run is the only gap the proof gate reports (no extra "add a checklist" line while tests are red)
+- Bare `keelyard proof` shows the status (with `--json` too); usage errors name the real command (`keelyard code`)
+- `keelyard doctor` warns when Codex hooks are wired but `~/.codex/config.toml` has no keelyard MCP server
+- Windows: every file and stdin is read and written as UTF-8 (non-Latin text and emoji no longer depend on cp1252)
+
+### OpenCode 2
+- The OpenCode plugin supports OpenCode 2.x (`setup(ctx)`: context, compaction, prompt, tool and event hooks, MCP via
+  `ctx.mcp.transform`) and 1.x (`server()`) from one file, now installed to `.opencode/plugins/keelyard.js`
+- Fix: shell output from OpenCode (`bash`) and Codex (`shell`) was never filtered; only Claude's `Bash` was
+
+### Cooperative swarm
+- `keelyard.coop`: planner -> workers -> verifier with a shared blackboard, a optional peer critic, voting, cheapest-capable
+  model routing (`[swarm].ladder`), and hard token budgets (`budget_tokens`, `task_budget_tokens`) enforced by
+  reserving each call's worst case before it is sent. On by default (`cooperative = true`, `--basic` to opt out)
+- Tested with 250 tasks and more than 200 calls in flight; token totals match exactly
+
+### Smaller footprint, workflow pack
+- MCP server exposes 13 core tools by default (`[mcp] tools = "core"`, or `"all"`, or a list); schemas
+  drop pydantic titles. Measured: 1,582 vs 2,401 tokens per session (`bench/overhead.py`)
+- Workflow pack: `workflow("plan"|"debug"|"review")` MCP tool, `/keelyard:plan|debug|review` for Claude Code,
+  `keelyard-*` commands for OpenCode; installed by `init`, loaded only when asked for
+- Compact guide block and brief rules; "be terse" rule
+- Destructive-command check ignores text inside quotes (unless run via `bash -c`, `eval`, `ssh`) and only
+  flags SQL when a SQL client is involved
+- Snapshots skip keelyard's own wiring files and no longer force-add ignored files in untracked folders
+- Screens and hero GIF show `~/` paths; release workflow with PyPI trusted publishing; gitleaks allowlist for test fixtures
+
+### Always on and stronger helpers
+- Brief at session start and after compaction, past-session recall per prompt, outline/diff on repeat reads
+- Snapshot before destructive commands; rate-limited hints (no tests nearby, session budget); `[brain]` config
+- Swarm: `swarm_plan`, context packs, JSON answers, one-definition rewrites, patches tested in a copy,
+  best-of-N, retry with feedback, escalation, `subagent_tasks` for the host agent's subagents
+- Windows CI; fixes for Windows paths, cp1252 output, CRLF diffs, racing state directory
+
+### CLI overhaul (breaking renames)
+- `x` → `run`, `compress` → `filter`, `timeline` → `rewind list -i`, `mem` → `memory`, `sym`/`map`/`outline` → `code find|map|outline`, `proof req` → `proof add`
+- New `init` (detects Claude Code, Codex, OpenCode), `doctor`, `status`, `selftest`
+- `--json` on every command, stable exit codes (0 ok, 1 error, 2 usage, 3 check failed), errors with hints
+- Agent environment: 20 structured MCP tools, CLAUDE.md/AGENTS.md guide block, Claude Code skill and slash commands
+- New design: Geist-based proof and arena reports, textual timeline, mkdocs-material docs site
+- 35 bugs fixed from adversarial QA (see tests/test_adversarial.py)
+
+### Initial
+
+- Proof gate (Stop hook), HTML proof report
+- Rewind: shadow-git snapshots, rewind/fork, curses timeline
+- Helper swarm with citation and patch verification
+- Saver: read dedupe, command-aware output filters (git, pytest, cargo/go/jest, grep, find, ruff/eslint/mypy),
+  Claude Code PostToolUse output replacement, `recall`
+- Structure-first reading: `outline`, `project_map`, `find_symbol`
+- Unified memory (SQLite FTS5) and usage report across Claude Code, Codex, OpenCode
+- Arena: one task across agents/models, tokens/cost/pass rate, HTML (+PNG) report
+- Benchmarks: compression corpus, snapshot timing, head-to-head vs rtk with fact retention

keelyard-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at a private GitHub Security Advisory on this repository (or by contacting the maintainer listed in pyproject.toml). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations