apatch 0.8.42__tar.gz

apatch-0.8.42/LICENSE

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

apatch-0.8.42/PKG-INFO

@@ -0,0 +1,432 @@
+Metadata-Version: 2.4
+Name: apatch
+Version: 0.8.42
+Summary: Agent Patch & Trace Analyzer (apatch) - AST-Fuzzy matching & interactive agent patch reviewer
+Author: Ed Cherednik
+License-Expression: MIT
+Keywords: ast,tree-sitter,patch,diff,llm,agent,refactor
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: tree-sitter-cpp>=0.21.0
+Requires-Dist: tree-sitter-python>=0.21.0
+Requires-Dist: tree-sitter-javascript>=0.21.0
+Requires-Dist: tree-sitter-typescript>=0.21.0
+Requires-Dist: tree-sitter-rust>=0.21.0
+Requires-Dist: tree-sitter-go>=0.21.0
+Provides-Extra: trustchain
+Requires-Dist: trustchain; extra == "trustchain"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: languages
+Requires-Dist: tree-sitter-java>=0.21.0; extra == "languages"
+Requires-Dist: tree-sitter-c-sharp>=0.21.0; extra == "languages"
+Requires-Dist: tree-sitter-ruby>=0.21.0; extra == "languages"
+Requires-Dist: tree-sitter-php>=0.22.0; extra == "languages"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: wheel>=0.43; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
+Provides-Extra: platform
+Requires-Dist: httpx>=0.27.0; extra == "platform"
+Requires-Dist: cryptography>=42.0.0; extra == "platform"
+Provides-Extra: mcp
+Requires-Dist: mcp<2.0.0,>=1.0.0; extra == "mcp"
+Dynamic: license-file
+
+# apatch — Agent Patch & Trace Analyzer 🚀🛡️
+
+ИИ-агент сломал файл на 7-м шаге из 10? `apatch` применит ровно нужные шаги из лога — даже если файл с тех пор изменился.
+
+`apatch` — это специализированный инструмент для надежного применения правок кода и документации ИИ-агентов (Cursor, Claude Code, Antigravity, Gemini), безопасного декомпозирования монолитов и ведения транзакционных баз знаний без context drift.
+
+---
+
+## Что это решает? (Проблема Context Drift)
+
+Представьте классическую ситуацию: вы работаете с ИИ-агентом. Он предлагает вам изменение в файле кода или документации. Но пока вы обсуждали детали или запускали тесты, в файл были внесены косметические изменения, добавлены комментарии, изменены отступы или перефразированы абзацы. Контекст «уплыл» (**context drift**).
+
+Обычный инструмент замены (`str_replace` или `git apply`) выбросит ошибку `«Строка не найдена»`. 
+
+`apatch` решает эту проблему с помощью **многоуровневых алгоритмов сопоставления и стабильного непозиционного анкерования (Semantic ID Anchoring)**, позволяя хирургически применять изменения даже в уплывший контекст исходного кода и документации.
+
+---
+
+## Главные фичи «из коробки»
+
+### 💻 Для кода
+* **Транзакционный Matcher кода:**
+  * **Level 1 (Exact):** Буквальное посимвольное совпадение.
+  * **Level 2 (Whitespace-Fuzzy):** Нечувствительный к пробелам, табам и пустым строкам поиск.
+  * **Level 3 (AST-Fuzzy):** Синтаксическое сопоставление через грамматики **tree-sitter**. Находит узел по имени (метод класса в C++ или Python), при нескольких одноимённых узлах **дизамбигуирует** по охватывающему классу и схожести тела, и **заменяет только тело функции**, сохраняя сигнатуру родительского файла нетронутой. Если предложенная правка меняла сигнатуру — выводится предупреждение (тело-only замена). Из коробки: C++, Python, JavaScript, TypeScript, Rust, Go; опционально (extra `languages`): Java, C#, Ruby, PHP, Kotlin, Swift.
+* **Умная декомпозиция и дедупликация (`apatch strip`):**
+  * Вырезает логические блоки кода во внешние файлы с авторазрешением коллизий имен.
+  * Генерирует отчет связей `extraction_report.json`.
+  * **Автоматически минимизирует зависимости:** оставляет в `parent_imports` только те заголовки/импорты, которые реально используются в вырезанном коде, и очищает `accessed_external_members` от шума STL-контейнеров (типа `size()`, `empty()`).
+
+### 📝 Для документов (Markdown)
+* **Непозиционный Matcher Документов:**
+  * **Semantic ID Anchor:** Автоматически находит стабильный тег якоря `<!-- @sid:claim_N -->` и полностью заменяет ассоциированный с ним логический блок, делая правки абсолютно устойчивыми к перефразированию, расширению или перемещению текста внутри файла.
+  * **Jaccard Similarity Fallback:** Нечеткое сопоставление абзацев на основе пересечения слов (коэффициент Жаккара) при отсутствии маркерных тегов разметки.
+* **Авторазметка и компиляция (`apatch compile`):** Автоматическая генерация стабильных семантических якорей и построение локальных графов знаний `knowledge_map.json` без внешних SaaS-зависимостей.
+
+### 🛡️ Для всего (Общие механизмы)
+* **Парсинг логов ИИ-агентов (Ingestor):** Автоматически выгружает кандидатов на правки из сырых `.jsonl` логов Cursor, Anthropic, Antigravity и стандартного Gemini API; распознаёт вложенные **unified-diff** и envelope **`apply_patch` (V4A)** в полях `diff` / `input` / `patch`.
+* **Обнаружение транскриптов (`apatch scan`):** Ищет свежие `.jsonl` в `~/.cursor`, `~/.claude`, `~/.gemini` и текущей папке — не нужно вручную копировать путь из IDE.
+* **Сухой прогон (`apatch plan`):** Показывает, как каждая правка ляжет на диск (путь, стратегия, **confidence**, предупреждения) без записи файлов.
+* **Умные пути (`apatch.resolver`):** Общий модуль `resolve_smart_path` — каскад из 4 уровней (exact → relative → strip prefix → recursive basename) с защитой от path traversal; одинаковая логика для `scan`, `plan` и `apply`. Session-scoped **`PathIndex`** (git ls-files или один pruned walk) ускоряет batch `plan`/`apply` на больших деревьях — см. [ADR-001](./docs/adr/ADR-001_Enterprise_Scale_Gaps.md). Опционально: `APATCH_PATH_BACKEND=fd|watchman|git|walk`.
+* **Enterprise scale:** `APATCH_AST_WINDOW_BYTES` / `APATCH_AST_FULL_PARSE_MAX` — windowed AST на больших файлах; `apatch plan --json --workers N` — параллельный dry-run.
+* **Транзакции шагов (Step-Level Transactions):** Полная атомарность многофайловых шагов рефакторинга. Перед началом шага бэкапятся все файлы. В случае падения сборки или тестов выполняется **автоматический откат всего шага**.
+* **Интеграция с крипто-реестром TrustChain:** Автоматическая фиксация каждого успешного шага в неизменяемом журнале.
+* **Символьная привязка аттестаций (RFP-032):** дрейф требования считается по границам символов (функции/классы, tree-sitter), а не по хэшу всего файла — правка одной функции не роняет требования, завязанные на другие символы того же файла (`apatch/symbol_anchor.py`). Слепое пятно — кросс-файловые ссылки — закрывает RFP-033 (ниже).
+* **Непрерывный конформанс (RFP-035):** стоячий contract-gate — `apatch conformance gate` классифицирует **весь** контракт разом (`conformant / drifted / stale / unproven`) и ловит спеки, аттестованные однажды и тихо протухшие. Блокирует только на **живом красном verify** (`drifted`), не на несвежей подписи (`stale`) — без ложных тревог. Opt-in (`.apatch/conformance.json`), scoped-прогоны (`--spec SPEC-X`), статический enrollment без рекурсии (`--no-live`), baseline-aware, ledger-free блокировка в CI (`--ci-safe`); что блокировать — выбор проекта. Доменный ярлык вроде `conformance: true` и само наличие SPEC не являются enrollment или доказательством: registration, live bucket и evidence qualification отчётно разделяются. См. [docs/conformance.md](./docs/conformance.md).
+* **Дифференциальный probe — `apatch probe` (RFP-005):** один примитив «возмути → пере-измерь → суди дельту против полярности», под который сведены три проверки качества гейта. `probe falsify` портит файлы, что охраняет требование, — verify **обязан** покраснеть (иначе это **ложный гейт**, не тестирующий охраняемое); `probe regress` — ни одного нового падения против записанного корпуса (baseline-aware); `probe ratify` — аттестованный гейт **всё ещё** зелёный (красный сейчас = протухшая аттестация). Универсально (`--verify` — любая shell-команда). См. [docs/probe.md](./docs/probe.md).
+* **Реестр реальности — `apatch reality` (RFP-005):** инверсия источника истины — append-only леждер наблюдаемых фактов, которые проект обязан закрыть (`.apatch/reality.jsonl`); требования спеки их **дискорджат** (`## Rk … (discharges: REC-…)`). `apatch reality status` считает покрытие как «наблюдаемая реальность, закрытая зелёным гейтом», а `uncovered` — выводимый долг, не ручной ярлык. См. [docs/reality.md](./docs/reality.md).
+* **Скаффолд спеки из контракта — `apatch spec scaffold --from-contract` (RFP-023):** authoring-инверсия проверки покрытия — из `## Acceptance`-таблицы RFP генерит скелет SPEC.md (по требованию на строку + traceability-гейт), **contract-complete by construction** (0 gaps). Заполняешь `(verify:)`, а не пишешь чеклист руками. Также MCP `apatch_spec_scaffold`.
+* **Кросс-файловый refactor-impact — `apatch scip impact` (RFP-033):** при рефакторинге символа показывает, какие **аттестованные** требования ссылаются на него из других файлов — слепое пятно символьных якорей. Граф ссылок строится **нативно из Python AST, без внешних зависимостей** (`.scip`-индекс точнее, если есть). Advisory — никогда не блок и не stale. Также MCP `apatch_scip`.
+* **Transparency anchor — governance, проверяемый в CI (A35-E):** локальный ledger доказывает governance только на машине, где он шёл; CI его не видит. Каждая governed-операция анкорится во **внешний append-only лог** (`trust-chain.ai`), op_id попадает в runtime `.apatch/inclusion.jsonl`, а проверенный subset публикуется в source-controlled `manifests/apatch-inclusion.jsonl`. CI-job `transparency-anchor` проверяет этот manifest против публичного Merkle-корня — без приватных зависимостей. Это первый гейт, который реально доказывает governance в CI (а не «обещает»). Сертификат агента авто-продлевается. См. [docs/transparency-anchor.md](./docs/transparency-anchor.md).
+* **Нормализация кодировок и переносов строк:** Автоматическое определение переносов строк (CRLF vs LF) и автодетект кодировок (UTF-8, CP1251, CP1252) при дисковых операциях с сохранением оригинальных параметров файлов.
+
+---
+
+## 🛡️ Что такое TrustChain и как это работает?
+
+**TrustChain** — это локальный криптографический фреймворк сквозного аудита разработки (разработка *Ed Cherednik*). 
+
+> [!IMPORTANT]
+> **TrustChain — это НЕ блокчейн.** У него нет распределенного консенсуса, майнеров, токенов или сети. Это локальный **подписанный хэш-чейн реестр (ledger)**, гарантирующий целостность и неизменяемость истории операций с помощью криптографии Ed25519.
+
+### Встроенный bootstrap без внешних зависимостей (Zero-Dependency)
+Для работы криптографического аудита в `apatch` **вам не требуется отдельно устанавливать TrustChain**. 
+`apatch` имеет встроенный Python-модуль резервного копирования и генерации структуры хэш-чейна:
+* Если в вашей системе **нет утилиты `tc`**, `apatch` автоматически инициализирует криптографический реестр во временных файлах структуры `.trustchain/` (папки `objects/`, `refs/`, `HEAD`, `config.json`), подписывая транзакции штатными средствами Python.
+* Если **CLI `tc` установлен в вашей системе**, `apatch` автоматически интегрируется с ним, вызывая глобальные команды `tc checkpoint` и `tc commit`.
+
+### Автоинициализация
+Вам не нужно вручную инициализировать аудит в каждом проекте. При первом запуске `apatch` автоматически ищет папку `.trustchain/` вверх по дереву папок. Если она не найдена — утилита **сама выполнит `tc init`** в корне вашего репозитория.
+
+### Режимы: audit vs enforce
+
+Проверка: `apatch doctor --json` → поле `trustchain.mode`:
+
+| `mode` | Когда | Поведение |
+|--------|-------|-----------|
+| `audit_pending` | Нет `.trustchain/` | Ledger создастся при первом apply/strip |
+| `audit` | Ledger есть, enforcement выкл | Checkpoint + commit; провал подписи **не** откатывает apply |
+| `enforce` | `.apatch/enforcement.json` | Пошаговая нотаризация, rollback, `no_trustchain` запрещён |
+
+Включить strict: `apatch init-consumer --with-enforcement`.
+
+
+---
+
+## Быстрый старт: executable specs (~10 мин)
+
+Один **data layer** (`project_status_workspace`, MCP `apatch_project_status`) — три представления для разных ролей ([RFP-020](docs/RFP-020-three-views.md)):
+
+| Роль | Вопрос | Команда |
+|------|--------|---------|
+| Developer | Что сломано / заблокировано? | `apatch status` · `--json` |
+| Architect | Где конфликты спек? | `apatch report --html` |
+| Manager | Мы в графике? | `apatch report --format md` |
+
+```bash
+# 1. Scaffold consumer (sandbox + enforcement — для governed apply)
+apatch init-consumer --target-dir . --with-sandbox --with-enforcement
+
+# 2. Диагностика окружения
+apatch doctor
+
+# 3. Executable spec: lint → dry-run → run (inline requirements или manifest)
+apatch spec lint --spec SPEC-YOUR-1
+apatch spec run --spec SPEC-YOUR-1 --dry-run
+# apatch spec run --spec SPEC-YOUR-1   # resume / MCP: apatch_spec_run
+
+# 4. Три представления одного DTO
+apatch status
+apatch spec list
+apatch report --html --out .apatch/report.html
+apatch report --format md --locale ru --out -
+```
+
+TrustChain фиксирует **кто / когда / что** attested — substrate для attribution ([RFP-020 §3](docs/RFP-020-three-views.md)).  
+Плейбук агента: [docs/AGENTS.template.md](./docs/AGENTS.template.md) · индекс спек: [docs/specs/README.md](./docs/specs/README.md).
+
+---
+
+## Документация
+
+Полная навигация по ролям (пользователь / агент / разработчик): **[docs/README.md](./docs/README.md)**
+
+| Нужно | Документ |
+|-------|----------|
+| Консоль — что делать (`i/l/p/a/v`) | [docs/console-guide.md](./docs/console-guide.md) |
+| Руководитель / ИБ — без кода | [docs/for-leaders.md](./docs/for-leaders.md) |
+| Доменная модель (Session / Invariant) | [docs/domain.md](./docs/domain.md) |
+| Грамматика команд | [docs/grammar.md](./docs/grammar.md) |
+| Security one-pager (enterprise) | [docs/security-one-pager.md](./docs/security-one-pager.md) |
+| Рецепты CLI | [docs/cookbook.md](./docs/cookbook.md) |
+| Непрерывный конформанс (contract-gate) | [docs/conformance.md](./docs/conformance.md) |
+| Transparency anchor — governance проверяемый в CI (A35-E) | [docs/transparency-anchor.md](./docs/transparency-anchor.md) |
+| ИИ-агент в проекте | [docs/AGENTS.template.md](./docs/AGENTS.template.md) |
+| MCP (15 default / 123 full) · [CHANGELOG](CHANGELOG.md) | [docs/mcp_setup.md](./docs/mcp_setup.md) · [runtime invariants](docs/governed-runtime-invariants.md) · [RFP-020 three views](docs/RFP-020-three-views.md) · [specs index](docs/specs/README.md) |
+| Локальный MCP roaming по sibling-репозиториям | [safe local workspace roaming](./docs/mcp_setup.md#safe-local-workspace-roaming) · [agent onboarding](./docs/agent-onboarding.md#0-resolve-the-workspace-contract) |
+| WorkAssets / Наработки | [for engineers](./docs/work-assets-engineering-guide.md) · [for directors](./docs/work-assets-director-brief.md) · [overview](./docs/work-assets.md) · [privacy/IP](./docs/work-assets-privacy-ip.md) · [data access](./docs/work-assets-data-access.md) · [portability](./docs/work-assets-portability-policy.md) · [consent/retention](./docs/work-assets-consent-retention.md) |
+| TrustChain collaborative work | [onboarding and operations](./docs/governed-work-trustchain.md) · [RFP-043](./docs/RFP-043-trustchain-governed-work-bindings.md) · [executable SPEC](./docs/specs/SPEC-GOVERNED-WORK-BINDINGS-1.md) |
+| Write sandbox | [docs/sandbox.md](./docs/sandbox.md) |
+| Оркестрация (arch, db, pipeline) | [docs/orchestration.md](./docs/orchestration.md) |
+| Strip / декомпозиция | [docs/strip_guide.md](./docs/strip_guide.md) |
+| Профили стека | [docs/profiles/](./docs/profiles/) |
+
+---
+
+## Установка
+
+### Системные требования
+- **Python:** 3.9–3.13 рекомендуется; 3.14 поддерживается, но при установленном пакете `trustchain` + `langchain-core` возможны предупреждения от LangChain (Pydantic v1). apatch их подавляет; долгосрочно — lazy-import в `trustchain.integrations`.
+- **ОС:** macOS или Linux.
+
+### Установка в виртуальном окружении:
+```bash
+# Создать и активировать окружение
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Базовая установка (C++, Python, JS/TS, Rust, Go — в core)
+pip install -e .
+
+# Опциональные extras (по необходимости)
+pip install -e ".[dev]"        # pytest для разработки
+pip install -e ".[yaml]"       # YAML-манифесты для strip/phase
+pip install -e ".[languages]"  # Java, C#, Ruby, PHP — AST-fuzzy (ленивая загрузка)
+pip install -e ".[trustchain]" # полный CLI tc (без него apatch всё равно bootstrap'ит .trustchain/)
+```
+
+| Extra | Назначение |
+| :--- | :--- |
+| *(core)* | `click`, `rich`, tree-sitter: cpp, python, javascript, typescript, rust, go |
+| `dev` | `pytest`, `pytest-asyncio` |
+| `yaml` | `pyyaml` — манифесты `strip` / `phase run` и structure-aware match для `*.yaml` mappings |
+| `languages` | `tree-sitter-java`, `tree-sitter-c-sharp`, `tree-sitter-ruby`, `tree-sitter-php` |
+| `trustchain` | пакет `trustchain` + CLI `tc` (опционально; встроенный fallback есть) |
+
+## Replay транскриптов IDE
+
+> **Вторичный путь** — когда нет governed SPEC. Для продуктового workflow начните с [быстрого старта executable specs](#быстрый-старт-executable-specs-10-м) выше.
+
+### Типовой workflow (scan → plan → apply)
+#### 1. Найти транскрипты агентов на машине
+```bash
+apatch scan                     # авто-поиск .jsonl: Cursor / Claude / Gemini / текущая папка
+apatch scan --path ./logs --json --no-count   # быстрее: без подсчёта кандидатов
+```
+*Печатает таблицу свежих логов (mtime, источник, путь, число кандидатов). `--limit N`, `--no-cwd`, `--path` — доп. каталоги.*
+
+#### 2. Просмотр кандидатов из лога
+```bash
+apatch view --logs transcript.jsonl
+apatch view --logs transcript.jsonl --json --tool StrReplace
+```
+*Список шагов: файл, действие, размеры old/new. Фильтры: `--tool`, `--filter`, `--steps`, `--range`.*
+
+#### 3. Сухой прогон: как лягут правки (без записи)
+```bash
+apatch plan --logs transcript.jsonl --target-dir . --diff
+apatch plan --logs transcript.jsonl --target-dir . --json
+```
+*Для каждого кандидата: `resolved_path`, `strategy`, `confidence` (0..1), `would_apply`, `warnings`, опционально `diff`. Те же фильтры, что у `view`/`apply`. Для Elastic/OpenSearch mappings при drift по whitespace или порядку ключей `strategy` будет `json-semantic` (JSON и YAML).*
+
+#### 4. Интерактивное применение правок (TUI с diff-просмотром)
+```bash
+apatch apply --logs transcript.jsonl --target-dir .
+```
+В процессе применения:
+* `[A] Apply` — применить правку (в TUI видны strategy, confidence и предупреждения AST-fuzzy).
+* `[S] Skip` — пропустить шаг.
+* `[E] Edit` — открыть фрагмент в `$EDITOR`, скорректировать и применить.
+
+#### 5. Programmatic batch refactoring (JSONL как вход)
+
+`apatch apply` принимает **любой** JSONL с полями `TargetContent` / `ReplacementContent` — не только транскрипты Cursor/Claude. Это полноценный **транзакционный batch-движок** для программируемых рефакторингов.
+
+```bash
+# Сгенерировать JSONL (скриптом или вручную)
+python3 -c '
+import json
+p = {"step_index": 1, "tool_calls": [{"name": "replace_file_content", "arguments": {
+    "TargetFile": "app/models.py",
+    "TargetContent": "old_pattern",
+    "ReplacementContent": "new_pattern",
+    "AllowMultiple": True
+}}]}
+print(json.dumps(p))
+' > patches.jsonl
+
+apatch plan --logs patches.jsonl --target-dir . --diff
+apatch apply --logs patches.jsonl --target-dir . --all -y \
+  --verify "pytest" --verify-deferred --report report.json
+```
+
+- `AllowMultiple: true` в JSONL **или** CLI `--all` — замена каждого вхождения (token-rename / pattern replace).
+- Альтернатива (replace по glob): `apatch generate --find ... --replace ... --glob '**/*.py' --out patches.jsonl`
+- **Новые файлы + правки + права файла:** `apatch generate-batch --needles needles.json --out patches.jsonl` — `action`: `create` | `replace` | `delete` | `rename` | `chmod` ([cookbook](./docs/cookbook.md))
+
+Готовые рецепты: **[docs/cookbook.md](./docs/cookbook.md)**.
+
+#### 5b. Оркестрация изменений (архитектура, БД, impact)
+
+```bash
+apatch impact UserModel --json              # что затронет правка
+apatch arch check --json                  # manifests/arch-rules.yaml
+apatch db check --profile sqlalchemy --json # модели без миграции?
+apatch db revision --profile sqlalchemy -m "msg" --dry-run
+apatch db safety --profile sqlalchemy --json
+apatch db run --manifest manifests/db-refactor.json --dry-run
+
+apatch apply --logs patches.jsonl -y --budget medium   # лимит объёма правок (R49)
+apatch refactor run --manifest manifests/refactor-bundle.example.json --dry-run
+apatch verify semantic --json                         # routes/OpenAPI не исчезли
+apatch pipeline run --manifest manifests/engineering-pipeline.example.json --dry-run
+apatch index build && apatch index query UserModel
+apatch trustchain history --query ADR-000
+apatch init-consumer --with-arch-rules   # arch rules + pipeline template in manifests/
+```
+
+Оркестрация: **[docs/orchestration.md](./docs/orchestration.md)**.
+
+#### 6. Автопилот с верификацией сборки/тестов
+```bash
+apatch apply --logs transcript.jsonl --target-dir . --yes --verify "pytest"
+
+# Безопасный batch: применять только дрейфанувшие правки и только при высокой уверенности,
+# с машинно-читаемым отчётом сессии
+apatch apply --logs transcript.jsonl --target-dir . --yes \
+  --only-drifted --min-confidence 0.85 --report apatch_report.json
+```
+*Если на каком-то шаге тесты упадут, `apatch` мгновенно выполнит атомарный откат этого шага. `--only-drifted` пропускает точные совпадения (там помощь не нужна), `--min-confidence` не даёт автопилоту молча применять низкоуверенные fuzzy-совпадения, а `--report` пишет JSON с тем, что и какой стратегией применилось.*
+
+> [!WARNING]
+> `--verify` и `--post-hook` выполняют переданную строку через **системный shell** (`shell=True`), а `[E] Edit` запускает `$EDITOR`. Запускайте только доверенные команды.
+>
+> **Verify gotchas:** сложный inline Python с кавычками или glob `**` часто ломается из-за shell-escaping — verify падает, apatch откатывает шаг, хотя патчи были корректны. Предпочитайте отдельный скрипт: `--verify "npm run build"`, `--verify "./scripts/check.sh"`, `--verify "pytest"`. При падении verify apatch печатает полный stdout/stderr.
+
+#### 7. Восстановление исходного состояния
+```bash
+apatch rollback --target-dir .
+```
+Откатывает **файлы на диске** из `.apatch/backups/` и (если активен TrustChain) сбрасывает `HEAD` к checkpoint последней strip/apply-сессии.
+
+#### 8. Разметка документации (`compile`)
+```bash
+apatch compile doc.md --out-dir ./extracted
+```
+*Разбивает Markdown на логические блоки, инжектирует `<!-- @sid:claim_N -->`, генерирует `knowledge_map.json`.*
+
+#### 9. Декомпозиция монолита (`strip` / `phase run`)
+```bash
+# Пакетное вырезание + конвертация в native_eval_*.cpp
+apatch phase run \
+  --manifest manifests/eval_visitor_strips_phase12.json \
+  --file src/frontend/interpreter/eval_visitor.cpp \
+  --native-out-dir src/frontend/interpreter \
+  --out-dir extracted \
+  --verify "cmake --build build --target olang_interpreter_core"
+
+# STRICT: при blockers конвертера — exit 1 + откат исходника и артефактов
+apatch strip --file eval_visitor.cpp --manifest manifests/phase.json \
+  --native-out-dir interpreter/ --out-dir extracted --to-native auto --strict
+```
+Checkpoint apatch = **тот же** `apatch_strip_<timestamp>` в `.apatch/backups/` + TrustChain ref + подпись SHA-256 файлов в ledger. Откат checkpoint всегда восстанавливает диск и HEAD.
+
+> [!NOTE]
+> Само вырезание блоков (`strip`) и генерация отчётов — общего назначения. А конвертер `--to-native` (модуль `apatch.native_converter`) **специфичен для рантайма O-Lang / Ed Organism** (он генерирует `register_native(...)` под `Interpreter::Value` и т.п.). Для других C++ кодовых баз используйте `strip` для извлечения, а интеграцию пишите под свой проект.
+
+Подробнее: [docs/strip_guide.md](./docs/strip_guide.md).
+
+### Машинный вывод (`--json`) для агентов и CI
+
+| Команда | Формат |
+| :--- | :--- |
+| `scan --json` | `[{path, source, mtime, modified, size, candidate_count}, ...]` |
+| `view --json` | `[{step_index, tool_name, target_file, action_type, source_format, old_len, new_len, replace_all}, ...]` |
+| `plan --json` | `[{step_index, resolved_path, strategy, confidence, would_apply, warnings, diff}, ...]` |
+| `apply --report FILE` | `{target_dir, dry_run, checkpoint, applied, skipped, entries:[{outcome, strategy, confidence, warnings, ...}]}` |
+
+**Шкала confidence:** `exact`/`create`/`delete` → `1.0`; `whitespace-fuzzy` → `0.85`; `semantic-sid` → `0.95`; `document-fuzzy` → `0.7`; `ast-fuzzy` → схожесть тел (или fallback `0.6`–`0.8`); `failed` → `0.0`.
+
+Типовая цепочка для автономного агента:
+```bash
+apatch scan --json --limit 5 | jq '.[0].path' -r   # взять свежий лог
+apatch plan --logs "$(…)" --target-dir . --json    # оценить риск
+apatch apply --logs "$(…)" --target-dir . --yes \
+  --only-drifted --min-confidence 0.85 --report /tmp/apatch_report.json
+```
+
+---
+
+## Лицензия
+
+**APatch Studio** — один продукт с двумя планируемыми редакциями:
+**APatch Studio OSS** и **APatch Studio Pro**. Сейчас ни одна из них публично не
+выпущена: текущий репозиторий и runtime 0.8.36 остаются private/unreleased.
+
+[LICENSE](./LICENSE) и package metadata фиксируют выбранные MIT-условия для
+будущего публичного артефакта APatch Studio OSS, но сами по себе не являются
+публикацией. APatch Studio Pro будет распространяться на коммерческих условиях;
+Pro-only services, managed infrastructure and separately identified assets не
+получают MIT-лицензию автоматически.
+
+Personal / Workspace extensions сохраняют выбранные их авторами условия из
+manifest; использование стабильного out-of-process контракта не передаёт APatch
+право собственности, публикации или обучения на их коде и данных. Core, MCP,
+CLI, Companion и remote broker являются компонентами APatch Studio, а не
+отдельными продуктами. Каноническая граница редакций зафиксирована в
+[product matrix](./docs/product-matrix.md).
+
+При будущем публичном релизе MIT будет относиться только к first-party software,
+явно включённому в release artifact APatch Studio OSS. Отдельно обозначенные
+внешние материалы, включая `docs/ct_ckba_036_2017`, не входят в Python
+wheel/sdist и не получают MIT-лицензию автоматически; их происхождение и право
+распространения должны быть оформлены до включения в публичный release artifact.
+
+---
+
+## Тесты
+
+Проект содержит **299+ интеграционных тестов**, написанных без использования моков — все проверки работают с реальным синтаксическим деревом tree-sitter, файловой системой, Markdown CST-парсерами и живыми криптографическими цепочками.
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/
+```
+
+| Тестовый модуль | Что проверяет |
+| :--- | :--- |
+| `test_discovery.py` | `scan`: поиск `.jsonl`, подсчёт кандидатов, `--json`, изолированный `HOME` (без сканирования реального `~/.cursor`). |
+| `test_plan.py` | `plan --json`: exact/fail, `would_apply`, отсутствие записи на диск. |
+| `test_filters.py` | `--only-drifted`, `--min-confidence`, `--report` через TUI batch-режим. |
+| `test_ingestor.py` | Парсинг логов Cursor/Gemini/Anthropic, **unified-diff** и **apply_patch (V4A)** envelope. |
+| `test_features.py` | Пошаговые транзакции, автодетект CP1251 и CRLF, `--verify` / `--verify-deferred`, `CREATE`/`DELETE`. |
+| `test_matcher.py` | Exact / whitespace-fuzzy / AST-fuzzy, дизамбигуация overload, `MatchResult.evaluate`, предупреждение о смене сигнатуры, Java (если установлен `languages`). |
+| `test_semantic.py` | Markdown SID-якоря, `semantic-sid`, Jaccard `document-fuzzy`, `compile` CLI. |
+| `test_strip.py` | Вырезание блоков, `parent_imports`, `extraction_report.json`, манифесты, native-конвертер. |
+| `test_strip_rollback.py` | Транзакционный откат strip + TrustChain HEAD. |
+| `test_trustchain.py` | Чекпоинты, signed коммиты, автоинициализация `.trustchain/`. |
+| `test_tui.py` | TUI, ручное редактирование, path traversal. |
+
+---
+
+*Разработано Ed Cherednik, 2026.*