skopus 0.1.1__tar.gz

skopus-0.1.1/.github/workflows/bench-smoke.yml

@@ -0,0 +1,52 @@
+name: bench-smoke
+
+on:
+  pull_request:
+    branches: [main]
+
+# Runs the Correction-Persistence benchmark with the mock driver on every PR.
+# The mock driver is deterministic and free (no API cost), so this is safe
+# to run on every PR as a smoke test. Real benchmark runs (with an actual
+# LLM driver) happen manually or on a release cadence.
+
+jobs:
+  bench-smoke:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install skopus
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Initialize skopus (non-interactive)
+        run: |
+          mkdir -p /tmp/smoke-home
+          HOME=/tmp/smoke-home skopus init \
+            --non-interactive \
+            --name "CI" \
+            --profile bug-hunter \
+            --vault /tmp/smoke-home/Vault
+
+      - name: Run CP benchmark (mock driver, full ablation)
+        run: |
+          HOME=/tmp/smoke-home skopus bench run cp \
+            --ablation \
+            --driver mock \
+            --limit 5 \
+            --no-save
+
+      - name: Run single CP with mock (sanity)
+        run: |
+          HOME=/tmp/smoke-home skopus bench run cp \
+            --driver mock \
+            --limit 3 \
+            --no-save

skopus-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies (skopus + dev + graph-full)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check skopus tests bench
+
+      - name: Ruff format check
+        run: ruff format --check skopus tests bench
+
+      - name: Run pytest
+        run: pytest tests/ -v --tb=short
+
+      - name: Smoke test CLI
+        run: |
+          skopus version
+          skopus --help
+          skopus bench list

skopus-0.1.1/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# venv
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Benchmark outputs
+bench/results/
+bench/datasets/raw/
+
+# Skopus runtime artifacts (when testing)
+.skopus-test/

skopus-0.1.1/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to Skopus are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] — 2026-04-10
+
+Bug-fix release: `/graphify` was not actually invokable as a slash command
+in Claude Code after `skopus init`.
+
+### Fixed
+- **`/graphify` slash command missing in Claude Code** — graphify has two
+  install commands that do different things: `graphify install` (global,
+  one-time, copies the skill file to `~/.claude/skills/graphify/SKILL.md`)
+  and `graphify claude install` (per-project, writes CLAUDE.md block +
+  PreToolUse hook). Skopus was only calling the per-project one, which
+  meant `/graphify` was never a real slash command in Claude Code — only
+  the hook and CLAUDE.md block were installed. Fix: skopus now calls
+  `graphify install` (the global one-time step) before
+  `graphify claude install` during `skopus init`.
+
+### Added
+- `skopus.graphify_bridge.ensure_graphify_skill_installed()` — idempotent
+  helper that copies the graphify skill file if missing. Safe to call on
+  every `skopus init`. Short-circuits when the skill file already exists.
+- Two new tests covering the short-circuit and bool-return contract.
+
+### Testing
+- **97 tests passing**, 1 skipped (up from 95 in v0.1.0)
+
+---
+
+## [0.1.0] — 2026-04-10
+
+The **benchmark release**. Skopus is now measurable, reproducible, and
+compound-over-sessions with a full benchmark harness and a novel
+Correction-Persistence dataset.
+
+### Added
+- `bench/` package with a unified benchmark harness
+- **Correction-Persistence** benchmark (novel, skopus's research contribution):
+  - 20 scenarios at v0.1.0-alpha (target: 100+ for v1.0)
+  - Domains: code, prose, reasoning, tool-use
+  - Runner, scorer, and dataset loader
+- `LensConfig` — 5-config ablation framework:
+  - `vanilla` (no skopus)
+  - `charter` (+charter only)
+  - `charter+memory` (+charter +feedback memory)
+  - `charter+memory+vault` (+decisions and learnings)
+  - `full` (+graph via graphify MCP)
+- `LLMDriver` abstraction with two implementations:
+  - `MockDriver` — deterministic responses for testing without API cost
+  - `AnthropicDriver` — real Claude API calls (requires `ANTHROPIC_API_KEY`)
+- `bench.harness` — `run_benchmark`, `run_all`, `run_ablation`, `save_report`,
+  `format_markdown_report`
+- `bench.context.build_system_prompt` — converts a `LensConfig` to a system
+  prompt that encodes the corresponding amount of skopus context
+- Stub wrappers for `LongMemEval`, `LoCoMo`, `MSC`, and `RULER` with
+  integration paths documented (full runners planned for v0.1.1)
+- New CLI subcommands under `skopus bench`:
+  - `skopus bench list` — show available benchmarks
+  - `skopus bench run <name> [--lens | --ablation] [--driver] [--limit]`
+  - JSON results auto-saved to `bench/results/`
+- GitHub Actions workflow `.github/workflows/test.yml` — lint + typecheck +
+  full pytest on every push and PR
+- CHANGELOG.md
+
+### Changed
+- Package layout: `bench/` now shipped as a sibling package inside the wheel
+- `skopus init` auto-tracks the current directory as a linked project when
+  an adapter is wired (previously only `skopus link` did)
+
+### Testing
+- **95 tests passing**, 1 skipped (up from 72 in v0.0.3)
+- New test files:
+  - `tests/test_bench_cp.py` — Correction-Persistence coverage
+  - `tests/test_bench_harness.py` — harness dispatch, ablation, reports
+
+---
+
+## [0.0.3] — 2026-04-10
+
+Multi-agent expansion — five new platform adapters plus the session-end
+reflection loop.
+
+### Added
+- `MarkdownAdapter` DRY base class in `skopus.adapters.base`
+- Five new platform adapters:
+  - `CursorAdapter` — `.cursor/rules/skopus.mdc` with `alwaysApply: true`
+  - `CodexAdapter` — `AGENTS.md`
+  - `AiderAdapter` — `AGENTS.md` with custom detect for `.aider.conf.yml`
+  - `GeminiCliAdapter` — `GEMINI.md`
+  - `CopilotCliAdapter` — `AGENTS.md` with gh/copilot binary detection
+- `skopus.evolve` — session-end reflection loop:
+  - Interactive 3-question prompt (validated calls, drifts, rules)
+  - Writes feedback files to `~/.skopus/memory/feedback/YYYY-MM-DD-<slug>.md`
+  - Appends drifts to `workflow_partnership.md §7`, wins to `§8`
+  - Auto-commits to `~/.skopus/.git`
+  - Programmatic mode for testing: `run_evolve(entries=[...])`
+- `skopus charter evolve` CLI command
+- `SKOPUS_SECTION_START/END` markers and `build_skopus_block()` moved from
+  `claude_code.py` to `base.py` (shared by all adapters)
+- 22 new tests covering the multi-adapter pattern + evolve
+
+### Changed
+- `claude_code.py` refactored to import shared helpers from `base.py`
+- Registry includes aliases (`gemini` → `gemini-cli`, `copilot` → `copilot-cli`)
+
+---
+
+## [0.0.2] — 2026-04-10
+
+Graphify integration + non-destructive init + `.claude/CLAUDE.md` preference.
+
+### Added
+- **Graphify as a hard dependency** (`graphifyy>=0.1`) — the fourth lens
+  ships with every install
+- `skopus.graphify_bridge` — installation helpers:
+  - `install_graphify_for_claude()` — runs `graphify claude install` +
+    `graphify hook install` in a project
+  - `_consolidate_graphify_block()` — moves graphify's block from root
+    `CLAUDE.md` into `.claude/CLAUDE.md` (skopus convention)
+  - `first_build_hint()` — reads scope hint for the first-build reminder
+- `skopus init` auto-wires graphify into linked projects
+- `skopus doctor` reports per-project graph status
+- `--force` flag on `skopus init` for explicit overwrite
+- `MaterializeReport` return type with `written` and `skipped` lists
+- `claude_md_path()` helper preferring `.claude/CLAUDE.md` over root
+- 11 new tests covering graphify bridge, path resolution, non-destructive merge
+
+### Changed
+- `renderer.materialize()` is non-destructive by default — existing files are
+  preserved unless `force=True` is passed
+- `claude_code.adapter.install()` now prefers `<project>/.claude/CLAUDE.md`
+- `adapters.lock` now tracks the vault location explicitly
+
+### Fixed
+- `git commit` during init now uses inline identity flags so it works
+  without a configured global git user/email
+- Initial branch set to `main` (instead of `master`)
+- `skopus init` + `skopus link` both update `projects.json` via
+  the shared `_track_linked_project()` helper
+
+---
+
+## [0.0.1] — 2026-04-10
+
+Initial bootstrap. The four-lens model as runnable code.
+
+### Added
+- Core Python package scaffold (`skopus/`, `pyproject.toml`, `Makefile`,
+  `docs/DESIGN.md`, MIT `LICENSE`, `README.md`)
+- Bundled Jinja2 markdown templates for charter, memory, and vault
+- `skopus init` — interactive wizard (10 questions, `questionary`)
+- `skopus link` / `skopus unlink` — per-project adapter wiring
+- `skopus doctor` — health check
+- `Adapter` ABC + `ClaudeCodeAdapter` reference implementation
+- 24 initial tests
+
+### Design decisions locked
+- Four-lens mental model: charter, memory, vault, graph
+- Monorepo with Python package + bench subpackage
+- Non-destructive-by-default init
+- Multi-agent from day one
+- Benchmarks as first-class CI-gated deliverable
+- Graphify integration as the structural knowledge layer
+- Personalization via interactive wizard + `/charter-evolve` loop
+
+See [`docs/DESIGN.md`](docs/DESIGN.md) for the full spec.

skopus-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Valentin and Skopus 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.

skopus-0.1.1/Makefile

@@ -0,0 +1,31 @@
+.PHONY: install dev test lint typecheck fmt clean build
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+test:
+	pytest
+
+lint:
+	ruff check skopus tests
+
+fmt:
+	ruff format skopus tests
+
+typecheck:
+	mypy skopus
+
+ci: lint typecheck test
+
+clean:
+	rm -rf build dist *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type d -name .pytest_cache -exec rm -rf {} +
+	find . -type d -name .mypy_cache -exec rm -rf {} +
+	find . -type d -name .ruff_cache -exec rm -rf {} +
+
+build:
+	python -m build

skopus-0.1.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: skopus
+Version: 0.1.1
+Summary: Persistent four-lens context for AI coding assistants — charter, memory, vault, graph. One install, multi-agent, benchmark-driven.
+Project-URL: Homepage, https://github.com/cvalentinhorizontes/skopus
+Project-URL: Documentation, https://github.com/cvalentinhorizontes/skopus/blob/main/docs/DESIGN.md
+Project-URL: Issues, https://github.com/cvalentinhorizontes/skopus/issues
+Project-URL: Repository, https://github.com/cvalentinhorizontes/skopus
+Author: Carlos Valentin
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude-code,codex,cursor,karpathy,knowledge-graph,llm-wiki,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: graphifyy[leiden,mcp,pdf,watch]>=0.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: bench
+Requires-Dist: datasets>=2.14; extra == 'bench'
+Requires-Dist: numpy>=1.26; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: video
+Requires-Dist: graphifyy[video]>=0.1; extra == 'video'
+Description-Content-Type: text/markdown
+
+# Skopus
+
+**Persistent four-lens context for AI coding assistants.** Charter, memory, vault, graph — one install, multi-agent, benchmark-driven.
+
+> σκοπός *(skopos)* — Greek for *watcher*, *lookout*, *target*, *purpose*. The root of *scope*, *telescope*, *episcopal*. A system that gives agents durable scope across sessions.
+
+---
+
+## The problem
+
+Every AI coding assistant — Claude Code, Cursor, Codex, Aider, Gemini CLI, Copilot CLI — loses context at the end of every session. You teach them your preferences, they forget. You correct them, they repeat the mistake next week. Your hard-won lessons evaporate into chat history.
+
+The few persistent-memory systems that exist (claude-mem, Mem0, MemPalace, OpenAI memory) record conversations but don't encode *how you work* — the non-negotiables, the drift log, the anti-rationalization rules, the "do this, not that" patterns that actually make a collaboration compound. Meanwhile, structural knowledge about a codebase gets rediscovered every session via grep because nothing persists the map.
+
+The result: agents that are smart per-message but stupid across sessions, and humans who spend half their time re-teaching.
+
+## The promise
+
+A unified **four-lens context system** any AI coding assistant can load at session start:
+
+1. **Charter** — how you work together (non-negotiables, anti-rationalization table, drift log)
+2. **Memory** — what happened before (feedback, corrections, project state)
+3. **Vault** — what you decided and learned (narrative wiki, Karpathy `/raw` pattern)
+4. **Graph** — what the code looks like (via [graphify](https://github.com/safishamsi/graphify))
+
+One install. Works with 6+ agents. Ships with a benchmark suite that proves it works.
+
+## Quickstart
+
+```bash
+pip install skopus
+skopus init                    # interactive wizard (10 questions, ~5 min)
+cd my-project && skopus link   # wire the current project to your charter + vault
+skopus doctor                  # health check all four lenses
+```
+
+## What ships at v0.0.3 (alpha)
+
+- ✅ **Charter templates** — high-level `CLAUDE.md`, full `workflow_partnership.md`, `user_profile.md`
+- ✅ **Memory scaffold** — `MEMORY.md` index, feedback/project templates, 6 seed profiles
+- ✅ **Vault scaffold** — Karpathy `raw/wiki/output` layout with `/ingest`, `/compile`, `/query`, `/lint`, `/wiki` slash commands
+- ✅ **Interactive wizard** — 10-question personalization flow (+ `--non-interactive` for CI)
+- ✅ **Non-destructive init** — re-running `skopus init` preserves user edits by default; `--force` to overwrite
+- ✅ **Six platform adapters** — Claude Code, Cursor, Codex, Aider, Gemini CLI, Copilot CLI. All idempotent with automatic backup.
+- ✅ **Graphify integration** — hard dependency, automatic wiring of graphify's PreToolUse hook + git post-commit hook, consolidation of graphify's block into `.claude/CLAUDE.md`
+- ✅ **`skopus charter evolve`** — session-end reflection loop. Three-question interactive prompt captures validated calls, drifts, and new rules into feedback memory and the charter's drift log. The mechanism that makes the charter compound.
+- ✅ **`skopus doctor`** — health check across all four lenses plus linked projects
+- 🚧 **Benchmark harness** — LongMemEval, LoCoMo, MSC, RULER, Correction-Persistence — planned for v0.1.0
+
+### Supported platforms (v0.0.3)
+
+| Platform | Context file | Detection |
+|---|---|---|
+| **Claude Code** | `.claude/CLAUDE.md` (preferred) or root `CLAUDE.md` | `~/.claude/` |
+| **Cursor** | `.cursor/rules/skopus.mdc` (alwaysApply: true) | `cursor` binary or `~/.cursor/` |
+| **Codex** (OpenAI) | `AGENTS.md` | `codex` binary or `~/.codex/` |
+| **Aider** | `AGENTS.md` | `aider` binary or `~/.aider.conf.yml` |
+| **Gemini CLI** | `GEMINI.md` | `gemini` binary or `~/.gemini/` |
+| **Copilot CLI** | `AGENTS.md` | `gh` / `copilot` binary or `~/.copilot/` |
+
+See [`docs/DESIGN.md`](docs/DESIGN.md) for the full spec and roadmap.
+
+## The benchmark pillar
+
+Skopus is designed to be **measurable**. The charter's core non-negotiable — *evidence over assumption* — is applied reflexively to the project itself. Every PR that touches the charter templates, adapter wiring, or wizard flow must move a benchmark number or explain why it's orthogonal.
+
+At v0.1.0, the `skopus bench run` harness will run:
+
+| Benchmark | What it tests |
+|---|---|
+| **LongMemEval** (Wu et al. 2024) | 6 memory abilities: single-session, multi-session, knowledge update, temporal reasoning, explicit/implicit refs |
+| **LoCoMo** (Google 2024) | Long multi-session conversations |
+| **MSC** (Facebook 2021) | Persona consistency across sessions |
+| **RULER** (NVIDIA 2024) | Long-context retrieval, up to 128K ctx |
+| **Skopus Correction-Persistence** (novel) | Does the agent apply yesterday's corrections to today's tasks? |
+
+The ablation mode measures the additive contribution of each lens:
+
+```bash
+skopus bench run all --ablation --agent claude-code
+# Runs vanilla / +charter / +memory / +vault / +graph — shows delta per lens
+```
+
+## Philosophy
+
+Skopus combines three existing patterns into one coherent system:
+
+- **Karpathy's LLM Knowledge Base** ([tweet](https://x.com/karpathy/status/2039805659525644595), [gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) — the `raw/wiki/output` three-folder split with Ingest/Query/Lint operations, framed as a modern Vannevar Bush Memex.
+- **The Partnership Charter** — evidence over assumption, premium quality, anti-rationalization tables, drift logs. A meta-workflow layer most agent setups don't have.
+- **Graphify** ([safishamsi/graphify](https://github.com/safishamsi/graphify)) — automatic structural knowledge graph extraction from any codebase with honest audit trails (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`).
+
+Nothing here is new on its own. The contribution is the **coherent integration** plus the **benchmark commitment** to prove it works.
+
+## Contributing
+
+New platform adapters welcome. Each adapter is a single Python file implementing a 5-method ABC (`detect`, `install`, `uninstall`, `status`, `session_end_hook`). See `skopus/adapters/base.py` and `skopus/adapters/claude_code.py` for the reference implementation.
+
+Benchmark dataset contributions welcome — especially for the Correction-Persistence benchmark, which ships with 100+ scenarios in `bench/correction_persistence/dataset.json`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

skopus-0.1.1/README.md

@@ -0,0 +1,102 @@
+# Skopus
+
+**Persistent four-lens context for AI coding assistants.** Charter, memory, vault, graph — one install, multi-agent, benchmark-driven.
+
+> σκοπός *(skopos)* — Greek for *watcher*, *lookout*, *target*, *purpose*. The root of *scope*, *telescope*, *episcopal*. A system that gives agents durable scope across sessions.
+
+---
+
+## The problem
+
+Every AI coding assistant — Claude Code, Cursor, Codex, Aider, Gemini CLI, Copilot CLI — loses context at the end of every session. You teach them your preferences, they forget. You correct them, they repeat the mistake next week. Your hard-won lessons evaporate into chat history.
+
+The few persistent-memory systems that exist (claude-mem, Mem0, MemPalace, OpenAI memory) record conversations but don't encode *how you work* — the non-negotiables, the drift log, the anti-rationalization rules, the "do this, not that" patterns that actually make a collaboration compound. Meanwhile, structural knowledge about a codebase gets rediscovered every session via grep because nothing persists the map.
+
+The result: agents that are smart per-message but stupid across sessions, and humans who spend half their time re-teaching.
+
+## The promise
+
+A unified **four-lens context system** any AI coding assistant can load at session start:
+
+1. **Charter** — how you work together (non-negotiables, anti-rationalization table, drift log)
+2. **Memory** — what happened before (feedback, corrections, project state)
+3. **Vault** — what you decided and learned (narrative wiki, Karpathy `/raw` pattern)
+4. **Graph** — what the code looks like (via [graphify](https://github.com/safishamsi/graphify))
+
+One install. Works with 6+ agents. Ships with a benchmark suite that proves it works.
+
+## Quickstart
+
+```bash
+pip install skopus
+skopus init                    # interactive wizard (10 questions, ~5 min)
+cd my-project && skopus link   # wire the current project to your charter + vault
+skopus doctor                  # health check all four lenses
+```
+
+## What ships at v0.0.3 (alpha)
+
+- ✅ **Charter templates** — high-level `CLAUDE.md`, full `workflow_partnership.md`, `user_profile.md`
+- ✅ **Memory scaffold** — `MEMORY.md` index, feedback/project templates, 6 seed profiles
+- ✅ **Vault scaffold** — Karpathy `raw/wiki/output` layout with `/ingest`, `/compile`, `/query`, `/lint`, `/wiki` slash commands
+- ✅ **Interactive wizard** — 10-question personalization flow (+ `--non-interactive` for CI)
+- ✅ **Non-destructive init** — re-running `skopus init` preserves user edits by default; `--force` to overwrite
+- ✅ **Six platform adapters** — Claude Code, Cursor, Codex, Aider, Gemini CLI, Copilot CLI. All idempotent with automatic backup.
+- ✅ **Graphify integration** — hard dependency, automatic wiring of graphify's PreToolUse hook + git post-commit hook, consolidation of graphify's block into `.claude/CLAUDE.md`
+- ✅ **`skopus charter evolve`** — session-end reflection loop. Three-question interactive prompt captures validated calls, drifts, and new rules into feedback memory and the charter's drift log. The mechanism that makes the charter compound.
+- ✅ **`skopus doctor`** — health check across all four lenses plus linked projects
+- 🚧 **Benchmark harness** — LongMemEval, LoCoMo, MSC, RULER, Correction-Persistence — planned for v0.1.0
+
+### Supported platforms (v0.0.3)
+
+| Platform | Context file | Detection |
+|---|---|---|
+| **Claude Code** | `.claude/CLAUDE.md` (preferred) or root `CLAUDE.md` | `~/.claude/` |
+| **Cursor** | `.cursor/rules/skopus.mdc` (alwaysApply: true) | `cursor` binary or `~/.cursor/` |
+| **Codex** (OpenAI) | `AGENTS.md` | `codex` binary or `~/.codex/` |
+| **Aider** | `AGENTS.md` | `aider` binary or `~/.aider.conf.yml` |
+| **Gemini CLI** | `GEMINI.md` | `gemini` binary or `~/.gemini/` |
+| **Copilot CLI** | `AGENTS.md` | `gh` / `copilot` binary or `~/.copilot/` |
+
+See [`docs/DESIGN.md`](docs/DESIGN.md) for the full spec and roadmap.
+
+## The benchmark pillar
+
+Skopus is designed to be **measurable**. The charter's core non-negotiable — *evidence over assumption* — is applied reflexively to the project itself. Every PR that touches the charter templates, adapter wiring, or wizard flow must move a benchmark number or explain why it's orthogonal.
+
+At v0.1.0, the `skopus bench run` harness will run:
+
+| Benchmark | What it tests |
+|---|---|
+| **LongMemEval** (Wu et al. 2024) | 6 memory abilities: single-session, multi-session, knowledge update, temporal reasoning, explicit/implicit refs |
+| **LoCoMo** (Google 2024) | Long multi-session conversations |
+| **MSC** (Facebook 2021) | Persona consistency across sessions |
+| **RULER** (NVIDIA 2024) | Long-context retrieval, up to 128K ctx |
+| **Skopus Correction-Persistence** (novel) | Does the agent apply yesterday's corrections to today's tasks? |
+
+The ablation mode measures the additive contribution of each lens:
+
+```bash
+skopus bench run all --ablation --agent claude-code
+# Runs vanilla / +charter / +memory / +vault / +graph — shows delta per lens
+```
+
+## Philosophy
+
+Skopus combines three existing patterns into one coherent system:
+
+- **Karpathy's LLM Knowledge Base** ([tweet](https://x.com/karpathy/status/2039805659525644595), [gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) — the `raw/wiki/output` three-folder split with Ingest/Query/Lint operations, framed as a modern Vannevar Bush Memex.
+- **The Partnership Charter** — evidence over assumption, premium quality, anti-rationalization tables, drift logs. A meta-workflow layer most agent setups don't have.
+- **Graphify** ([safishamsi/graphify](https://github.com/safishamsi/graphify)) — automatic structural knowledge graph extraction from any codebase with honest audit trails (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`).
+
+Nothing here is new on its own. The contribution is the **coherent integration** plus the **benchmark commitment** to prove it works.
+
+## Contributing
+
+New platform adapters welcome. Each adapter is a single Python file implementing a 5-method ABC (`detect`, `install`, `uninstall`, `status`, `session_end_hook`). See `skopus/adapters/base.py` and `skopus/adapters/claude_code.py` for the reference implementation.
+
+Benchmark dataset contributions welcome — especially for the Correction-Persistence benchmark, which ships with 100+ scenarios in `bench/correction_persistence/dataset.json`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

skopus-0.1.1/bench/__init__.py

@@ -0,0 +1,29 @@
+"""Skopus benchmark harness.
+
+Measures the additive contribution of each lens (charter, memory, vault,
+graph) against an LLM baseline across five benchmarks:
+
+  - LongMemEval (Wu et al. 2024)   — cross-session memory
+  - LoCoMo (Google 2024)           — long multi-session conversations
+  - MSC (Facebook 2021)            — persona consistency
+  - RULER (NVIDIA 2024)            — long-context retrieval
+  - Correction-Persistence (novel) — does yesterday's correction persist today?
+
+The harness ships with five lens configurations for ablation:
+
+  1. vanilla              — LLM call, no skopus context
+  2. +charter             — charter loaded into system prompt
+  3. +charter +memory     — + feedback/project memory files
+  4. +charter +memory +vault — + relevant vault pages
+  5. full skopus          — + graphify MCP tools available
+
+Running:
+
+    skopus bench run cp                        # Correction-Persistence only
+    skopus bench run all                       # All 5 benchmarks
+    skopus bench run all --ablation            # Ablation across 5 configs
+    skopus bench list                          # Show available benchmarks
+    skopus bench report                        # Render markdown report from results
+"""
+
+__version__ = "0.1.0-alpha"