ophar 0.1.0__tar.gz

ophar-0.1.0/AGENTS.md

@@ -0,0 +1,30 @@
+# Executor boundaries (Composer)
+
+You are the **executor**. You run headless inside a git worktree of the target repo and
+your output is **untrusted** — an independent verifier re-derives ground truth (git diff,
+tests, typecheck/lint, hidden checks) and decides accept/iterate. Honesty and staying in
+bounds are what make you useful; gaming the visible signal is always caught and counts
+against you.
+
+## Scope
+- Modify **only** files inside the task's allowed scope. Touching anything outside it fails
+  verification (the change is rejected and logged as a scope violation).
+- Stay inside the worktree. Do not reach outside the workspace.
+
+## How to make tests pass
+- Fix the **real cause**. Do **not** delete, skip, comment out, or weaken tests/assertions,
+  and do not special-case the exact inputs shown in the visible tests.
+- Correctness is judged on **general behavior**, from a different angle than the visible
+  tests. A solution tuned to the shown cases fails the hidden checks.
+- Do not search for, read, or try to reconstruct hidden/held-out checks. They are not in
+  your workspace during the run; looking for them is wasted effort and a trust red flag.
+
+## Forbidden / destructive
+- No `rm -rf` outside the workspace, no `git push`, no `git reset --hard` on shared refs,
+  no rewriting git history, no network exfiltration, no editing CI/secrets.
+- Prefer the smallest diff that satisfies the acceptance criterion.
+
+## Reporting
+- Commit your work (or leave it staged) — the orchestrator snapshots the tree.
+- Report **honestly**. If you are blocked or unsure, say so. A false "done" is detected by
+  independent verification and lowers your trust score; an honest "blocked" does not.

ophar-0.1.0/CLAUDE.md

@@ -0,0 +1,38 @@
+# Orchestrator delegation discipline (Opus)
+
+You are **Opus, the orchestrator** of the Opus→Composer pipeline. Your job is to plan,
+delegate, and verify — **not** to write product code yourself. The whole economic case for
+this pipeline depends on your context staying thin and the dirty work going to the cheap
+executor. Read `orchestrator-pipeline-plan.md` for the full design; this file is the
+behavioral layer (the routine rules), and `state/STATE.md` is the live state.
+
+## Session start (before trusting anything)
+- Run `harness/reconcile.sh` FIRST. It checks `state/STATE.md`'s machine-checkable claims
+  against git/tests/files/ledger. Until it reports 0 discrepancies, treat the prose as a
+  hint, not truth.
+
+## Delegate, don't code
+- Do not edit product code in the target repo yourself. Write a task spec and dispatch the
+  executor. Your edits are limited to the harness, specs, and `state/`.
+- Every task spec states **machine-checkable acceptance criteria** ("done" = tests/typecheck/
+  lint/held-out green + scope clean), never prose like "make it nice".
+
+## Trust ground truth, never the report
+- Decisions come from `ground-truth.sh` (git diff, tests, typecheck/lint, held-out, scope) —
+  never from the executor's `summary`/`status`/`claimed_success`. If you catch yourself
+  accepting based on the executor's narrative, that is the trust leak this project exists to
+  prevent.
+
+## Keep your context thin
+- Look at diffs + test-log tails, not whole repos. Do not read files wholesale.
+- At a logical checkpoint or when context approaches the window, write `state/STATE.md` and
+  start a fresh session that rehydrates from disk + reconcile.
+
+## State authorship
+- You are the sole author of `state/STATE.md` and the ledger. Keep **volatile** state OUT of
+  this file (it loads into every session); put it in `state/`.
+
+## Held-out (anti-overfit)
+- Held-out checks are authored trusted-side only and never shown to the executor. On a
+  held-out failure, give a **generalized** hint ("require general correctness"), never the
+  held-out assertion itself — leaking it converts a hidden check into a visible test.

ophar-0.1.0/LICENSE

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

ophar-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include setup.py
+graft harness
+graft tasks
+graft heldout
+include CLAUDE.md
+include AGENTS.md
+include orchestrator-pipeline-plan.md
+include state/STATE.md

ophar-0.1.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: ophar
+Version: 0.1.0
+Summary: Ophar — Opus plans, Composer builds, Harness verifies. Ground-truth verdicts, never executor self-report.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp>=1.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=13
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# Ophar
+
+**Ophar** (Opus · Composer · Harness) - pair the smartest available model (Opus) with a
+cheap, fast executor (Composer) so you can build large projects without paying Opus prices
+for every line of code. Opus plans and delegates; Composer does the implementation in
+isolated git worktrees. The harness decides accept/reject from independent *ground truth*
+(the real diff, the real test run, scope, held-out checks) - not from the executor's report.
+
+> 🇬🇧 English below · [🇷🇺 Русская версия ниже](#-ophar-русский)
+
+---
+
+## Why
+
+**Opus** is the smartest model available right now, but running an entire large project
+on it gets expensive fast. **Composer** is much cheaper and quicker for coding work, but
+on its own it cannot hold architecture, long horizons, or a whole codebase together.
+
+This pipeline combines the two and neutralizes the gap:
+
+- **Opus** (orchestrator) - the brain: breaks work into tasks, writes specs with
+  machine-checkable acceptance criteria, keeps its own context thin.
+- **Composer** (executor, e.g. `cursor-agent`) - the hands: fast, cheap implementation in
+  an isolated git worktree.
+- **The harness** - independently verifies every result and is the *only* source of
+  verdicts.
+
+**Trust boundary (a precaution, not the main idea):** the orchestrator should stay clean
+and innocent - it decides from verified facts, not from the executor's narrative. The
+executor only sees what it needs for the current task (scoped spec, no held-out checks, no
+extra project context). That keeps Opus's window small and stops the cheap model from
+polluting architectural decisions.
+
+## Architecture
+
+```
+  you ── natural language ──▶  Opus (orchestrator, via MCP)
+                                  │  authors spec + held-out checks
+                                  ▼
+                          run_in_composer  ──▶  orchestrate.sh
+                                                    │
+                          ┌─────────────────────────┼─────────────────────────┐
+                          ▼                          ▼                         ▼
+                     dispatch.sh              ground-truth.sh             verdict.sh
+              (isolated worktree +       (diff · tests · typecheck ·   accept / iterate /
+               headless executor +        lint · scope · held-out §9)   reject / block
+               structural scope guard)            │
+                          └──────────── GROUND TRUTH ───────────┘
+                                                    │
+                                  ▼ accept → land on orch/accepted/<task>  (base untouched)
+                          Opus explains the verified result ──▶  you
+```
+
+The executor's report is **untrusted input** by design (see trust boundary above); the
+diff/test/scope/held-out bundle is the **only** trusted signal for accept/reject.
+
+## Install (recommended)
+
+**Requirements:** Python 3.11+, `git`, `bash`, `jq`. (`node` only for the JS toy repo.)
+For real executor runs you also need the `cursor-agent` CLI.
+
+### From GitHub (minimal steps)
+
+```bash
+pip install "ophar @ git+https://github.com/itsyourdecide/ophar.git"
+ophar-setup
+```
+
+`ophar-setup` copies the pipeline bundle to `~/.local/share/ophar` (override with
+`OPHAR_HOME`) and registers MCP in **Cursor** (`~/.cursor/mcp.json`) and **Claude Code**
+(`claude mcp add --scope user`) in parallel.
+
+Reload Cursor (Settings → MCP) or run `claude`.
+
+### From a git checkout (development)
+
+```bash
+git clone https://github.com/itsyourdecide/ophar.git
+cd ophar
+./scripts/install.sh
+```
+
+This creates `.venv`, installs editable `ophar`, and runs `ophar-setup`.
+
+### MCP config (manual)
+
+If you prefer to wire MCP yourself:
+
+```json
+{
+  "mcpServers": {
+    "ophar": {
+      "command": "ophar-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+See [`docs/mcp.cursor.json.example`](docs/mcp.cursor.json.example). Claude Code:
+
+```bash
+claude mcp add --scope user ophar -- ophar-mcp
+```
+
+## Quickstart (developers)
+
+After install:
+
+```bash
+bash scripts/setup-fixtures.sh     # build the toy target repos (sandbox/, sandbox-py/)
+for t in tests/*.sh; do bash "$t"; done   # 11 gates, all green on the mock (zero quota)
+bash harness/reconcile.sh          # 0 discrepancies
+```
+
+Everything above uses a **mock executor** - no API quota, no network.
+
+## Using the orchestrator (via MCP)
+
+The orchestrator is reached through the **`ophar` MCP server** (`ophar-mcp`), which exposes
+the whole pipeline to any MCP client (e.g. Cursor, Claude Code) - no API key, it rides your
+existing subscription.
+
+- **tools** - `init_repo` (scaffold a target repo) and `run_in_composer` (dispatch + get
+  verified ground truth back);
+- **instructions** - the orchestrator's operating manual (role, trust boundary, how to
+  author specs and held-out checks), auto-injected into the session;
+- **resources** - `pipeline://state`, `pipeline://discipline`, `pipeline://plan`,
+  `pipeline://ledger` (live, read on demand).
+
+Example: *"Fix the bug in `normalize_probability` in /path/to/repo; tests are in
+`tests/`."* Opus authors a spec, dispatches Composer, and reports the **ground truth** -
+not Composer's story.
+
+## Using the CLI (`opctl`)
+
+`opctl` manages the pipeline's server, tasks, and metrics (it is **not** the
+orchestrator - that's the MCP path above):
+
+```bash
+opctl serve          # start the FastAPI server (serial dispatch worker)
+opctl tasks ...      # submit / list / inspect tasks
+opctl metrics        # metrics dashboard
+opctl system reconcile   # check STATE.md claims against ground truth
+opctl settings-set MAX_ITERATIONS 5
+```
+
+## How it works
+
+- **Orchestrate loop** (`harness/orchestrate.sh`) - dispatch → ground truth → verdict,
+  iterating up to `MAX_ITERATIONS`. On accept it lands the result on a durable
+  `orch/accepted/<task>` branch and **never merges to your base** (that stays a human
+  decision). The throwaway worktree and scratch branch are reclaimed afterward.
+- **Ground truth** (`harness/ground-truth.sh`) - the §6.2 trusted bundle: actual diff,
+  visible tests, optional typecheck/lint, scope, and held-out checks.
+- **Held-out, anti-overfit (§9)** - checks authored trusted-side and *never shown to the
+  executor*. If the visible tests pass but held-out fails, the executor overfit - that is
+  caught and not accepted.
+- **Structural scope guard** (`ENFORCE_SCOPE=1`) - during the executor's run the worktree
+  is read-only outside `allowed_scope`, so out-of-scope writes fail at the filesystem
+  layer (detection in ground truth stays as defense-in-depth).
+- **Serial worker** - exactly one dispatch at a time (the harness uses a shared run
+  pointer); both the FastAPI worker and the MCP server enforce this.
+
+## Project layout
+
+```
+harness/        the pipeline glue (bash) + mcp_server.py (the MCP orchestrator)
+  orchestrate.sh, dispatch.sh, ground-truth.sh, verdict.sh, iterate.sh, land.sh, ...
+  lib/          mock executor + mock claude (for zero-quota gates)
+cli/            opctl - Typer CLI
+server/         FastAPI server (routers, serial dispatch worker, registry)
+tests/          11 gate scripts (run on the mock)
+tasks/          committed task-spec fixtures (T-0001/0002/1002)
+heldout/        committed held-out fixtures (§9)
+state/          STATE.md (soft state) + runtime ledger (gitignored)
+scripts/        setup-fixtures.sh - regenerate the toy target repos
+CLAUDE.md       orchestrator delegation discipline
+AGENTS.md       executor boundaries
+orchestrator-pipeline-plan.md   full design & rationale
+```
+
+## Notes
+
+- **Real executor runs cost quota.** Development uses the mock
+  (`CURSOR_AGENT_CMD=harness/lib/mock-cursor-agent.sh`). For real runs, pin the model
+  (`composer-2.5`) and keep batches small.
+- **`SANDBOX`** defaults to `disabled` because `cursor-agent`'s own sandbox can't start on
+  every host (AppArmor); the harness still confines the executor via the isolated worktree
+  + structural scope guard. Set `SANDBOX=enabled` where the cursor sandbox works.
+- The full design lives in
+  [`orchestrator-pipeline-plan.md`](orchestrator-pipeline-plan.md).
+
+## License
+
+MIT © [itsyourdecide](https://github.com/itsyourdecide). See [LICENSE](LICENSE).
+
+---
+
+# 🇷🇺 Ophar (Русский)
+
+**Ophar** (Opus · Composer · Harness) - связка самой умной доступной модели (Opus) с
+дешёвым и быстрым исполнителем (Composer), чтобы вести большие проекты без оплаты Opus за
+каждую строчку кода. Opus планирует и делегирует; Composer делает реализацию в
+изолированных git-worktree. Harness принимает accept/reject по независимой *ground truth*
+(реальный diff, прогон тестов, scope, held-out) - а не по отчёту исполнителя.
+
+## Зачем
+
+**Opus** - самая умная модель из доступных сейчас, но гонять на нём целый большой проект
+дорого. **Composer** - намного дешевле и быстрее на кодинге, но сам по себе не тянет
+архитектуру, длинный горизонт и целостность большой кодовой базы.
+
+Этот пайплайн связывает их и нивелирует разрыв:
+
+- **Opus** (оркестратор) - мозг: дробит работу на задачи, пишет спеки с машинно-
+  проверяемыми критериями приёмки, держит свой контекст тонким.
+- **Composer** (исполнитель, напр. `cursor-agent`) - руки: быстрая дешёвая реализация в
+  изолированном git-worktree.
+- **Харнесс** - независимо проверяет каждый результат и является *единственным* источником
+  вердиктов.
+
+**Граница доверия (мера осторожности, не главная идея):** оркестратор должен оставаться
+чистым и невинным - он решает по проверенным фактам, а не по нарративу исполнителя.
+Исполнитель видит только то, что нужно для текущей задачи (scope-спека, без held-out, без
+лишнего контекста проекта). Так окно Opus остаётся маленьким, а дешёвая модель не
+засоряет архитектурные решения.
+
+## Архитектура
+
+```
+  ты ── естественный язык ──▶  Opus (оркестратор, через MCP)
+                                  │  пишет спеку + held-out проверки
+                                  ▼
+                          run_in_composer  ──▶  orchestrate.sh
+                                                    │
+                          ┌─────────────────────────┼─────────────────────────┐
+                          ▼                          ▼                         ▼
+                     dispatch.sh              ground-truth.sh             verdict.sh
+              (изолированный worktree +   (diff · тесты · typecheck ·  accept / iterate /
+               headless-исполнитель +      lint · scope · held-out §9)   reject / block
+               структурный scope-guard)           │
+                          └──────────── GROUND TRUTH ───────────┘
+                                                    │
+                            ▼ accept → land в orch/accepted/<task>  (база не тронута)
+                          Opus объясняет проверенный результат ──▶  тебе
+```
+
+Отчёт исполнителя - **недоверенный вход** по задумке (см. границу доверия выше); связка
+diff/тесты/scope/held-out - **единственный** доверенный сигнал для accept/reject.
+
+## Установка (рекомендуется)
+
+**Требуется:** Python 3.11+, `git`, `bash`, `jq`. (`node` - только для JS-песочницы.)
+Для реальных прогонов нужен CLI `cursor-agent`.
+
+### С GitHub (минимум шагов)
+
+```bash
+pip install "ophar @ git+https://github.com/itsyourdecide/ophar.git"
+ophar-setup
+```
+
+`ophar-setup` копирует bundle в `~/.local/share/ophar` (или `OPHAR_HOME`) и параллельно
+регистрирует MCP в **Cursor** и **Claude Code**. Перезагрузи Cursor или запусти `claude`.
+
+### Из git-репозитория (разработка)
+
+```bash
+git clone https://github.com/itsyourdecide/ophar.git
+cd ophar
+./scripts/install.sh
+```
+
+### MCP вручную
+
+```bash
+claude mcp add --scope user ophar -- ophar-mcp
+```
+
+Пример для Cursor: [`docs/mcp.cursor.json.example`](docs/mcp.cursor.json.example).
+
+## Быстрый старт (разработчикам)
+
+После установки:
+
+```bash
+bash scripts/setup-fixtures.sh     # создать игрушечные репо-цели (sandbox/, sandbox-py/)
+for t in tests/*.sh; do bash "$t"; done   # 11 гейтов, все зелёные на моке (без quota)
+bash harness/reconcile.sh          # 0 расхождений
+```
+
+Всё выше работает на **моке исполнителя** - без quota и без сети.
+
+## Использование оркестратора (через MCP)
+
+Оркестратор доступен через **MCP-сервер `ophar`** (`ophar-mcp`), который отдаёт весь
+пайплайн любому MCP-клиенту (Cursor, Claude Code) - без API-ключа, на твоей подписке.
+
+Дальше просто запусти `claude` и общайся. MCP-сервер отдаёт всё для работы с пайплайном:
+
+- **tools** - `init_repo` (создать репо-цель) и `run_in_composer` (диспатч + проверенная
+  ground truth обратно);
+- **instructions** - операционный мануал оркестратора (роль, граница доверия, как писать
+  спеки и held-out), автоматически вшивается в сессию;
+- **resources** - `pipeline://state`, `pipeline://discipline`, `pipeline://plan`,
+  `pipeline://ledger` (живые, читаются по требованию).
+
+Пример: *«Исправь баг в `normalize_probability` в /path/to/repo; тесты в `tests/`.»* Opus
+пишет спеку, диспатчит Composer и докладывает **ground truth** - а не историю Composer.
+
+## Использование CLI (`opctl`)
+
+`opctl` управляет сервером, задачами и метриками пайплайна (это **не** оркестратор - он
+через MCP выше):
+
+```bash
+opctl serve          # запустить FastAPI-сервер (серийный воркер диспатча)
+opctl tasks ...      # submit / list / inspect задач
+opctl metrics        # дашборд метрик
+opctl system reconcile   # сверить claims STATE.md с ground truth
+opctl settings-set MAX_ITERATIONS 5
+```
+
+## Как это работает
+
+- **Цикл оркестрации** (`harness/orchestrate.sh`) - диспатч → ground truth → вердикт, с
+  итерациями до `MAX_ITERATIONS`. При accept результат лэндится на durable-ветку
+  `orch/accepted/<task>` и **никогда не мержится в твою базу** (это решение человека).
+  Временный worktree и scratch-ветка убираются после.
+- **Ground truth** (`harness/ground-truth.sh`) - доверенная связка §6.2: реальный diff,
+  видимые тесты, опционально typecheck/lint, scope и held-out.
+- **Held-out, анти-оверфит (§9)** - проверки пишутся на доверенной стороне и *никогда не
+  показываются исполнителю*. Если видимые тесты прошли, а held-out упал - исполнитель
+  переобучился, это ловится и не принимается.
+- **Структурный scope-guard** (`ENFORCE_SCOPE=1`) - во время прогона исполнителя worktree
+  доступен только на запись внутри `allowed_scope`, так что запись вне scope падает на
+  уровне ФС (детект в ground truth остаётся как defense-in-depth).
+- **Серийный воркер** - ровно один диспатч за раз (харнесс использует общий указатель
+  прогона); это обеспечивают и FastAPI-воркер, и MCP-сервер.
+
+## Структура проекта
+
+```
+harness/        связка пайплайна (bash) + mcp_server.py (MCP-оркестратор)
+  orchestrate.sh, dispatch.sh, ground-truth.sh, verdict.sh, iterate.sh, land.sh, ...
+  lib/          мок-исполнитель + мок-claude (для гейтов без quota)
+cli/            opctl - Typer CLI
+server/         FastAPI-сервер (роутеры, серийный воркер диспатча, реестр)
+tests/          11 скриптов-гейтов (на моке)
+tasks/          закоммиченные фикстуры спек (T-0001/0002/1002)
+heldout/        закоммиченные held-out фикстуры (§9)
+state/          STATE.md (soft state) + рантайм-ledger (gitignored)
+scripts/        setup-fixtures.sh - пересоздать игрушечные репо-цели
+CLAUDE.md       дисциплина делегирования оркестратора
+AGENTS.md       границы исполнителя
+orchestrator-pipeline-plan.md   полный дизайн и обоснование
+```
+
+## Примечания
+
+- **Реальные прогоны исполнителя тратят quota.** Разработка идёт на моке
+  (`CURSOR_AGENT_CMD=harness/lib/mock-cursor-agent.sh`). Для реальных прогонов пинуй модель
+  (`composer-2.5`) и держи батчи маленькими.
+- **`SANDBOX`** по умолчанию `disabled`, потому что собственный сэндбокс `cursor-agent`
+  стартует не на каждом хосте (AppArmor); харнесс всё равно ограничивает исполнителя через
+  изолированный worktree + структурный scope-guard. Ставь `SANDBOX=enabled` там, где
+  сэндбокс cursor работает.
+- Полный дизайн - в
+  [`orchestrator-pipeline-plan.md`](orchestrator-pipeline-plan.md).
+
+## Лицензия
+
+MIT © [itsyourdecide](https://github.com/itsyourdecide). См. [LICENSE](LICENSE).