omniconductor 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to CONDUCTOR are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/); versioning is [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [0.4.1] — 2026-07-06
+
+### Fixed (docs)
+- **README status line** corrected to **v0.4.0** and the instruction-fidelity token-economy work re-labelled from "unreleased" to shipped (it landed in 0.4.0) — the 0.4.0 npm package page had still shown v0.3.0.
+- **Public GitHub Releases backfilled** (v0.3.0, v0.4.0) so the repo's Latest release matches the npm version.
+
+## [0.4.0] — 2026-07-05
+
+### Added — Token-economy: instruction-fidelity-first
+- **Lossless-before-lossy context reduction** — `meta-discipline.md` §5.7 rewritten to prefer clearing stale tool results (never touches user instructions) over lossy summarization, with four mandatory compaction safeguards (durable instructions in CLAUDE.md, explicit `/compact` preservation, `/clear` between tasks, re-verify after compaction). New `docs/CONTEXT-EDITING-GUIDE.md` (Claude-only) documents the API context-editing mechanism + memory tool, primary-source cited. — **ADR-035**.
+- **Output brevity** — new `meta-discipline.md` §5.9 + **Anti-Pattern 08 (`output-verbosity-narration`)**: answer-first, no re-printed file bodies, right-sized format (output is ~5× input), with an explicit fidelity guard. Anti-pattern count **7 → 8**. — **ADR-036**.
+- **Referenced-fact currency rule** — `spec-as-you-go.md` §2.2: when a change alters a fact other docs state (a count / list / table / version / cross-reference), grep for the old value and update **every** place in the same turn, or record a new fact that has no home.
+- **npm now ships the guides** — `docs/PROMPT-CACHING-GUIDE.md` + `docs/CONTEXT-EDITING-GUIDE.md` added to the package `files` allowlist (the token-economy rules reference them).
+
+### Changed
+- **`meta-discipline.md` §5.5** — concrete Tool Search Tool `defer_loading` guidance (>85% tool-context reduction); mirrored into Anti-Pattern 07.
+- **`meta-discipline.md` §6** — current model lineup/pricing snapshot; §6.4 recast as a fidelity rule (cheaper models guess missing params where Opus asks). — **ADR-036**.
+- **Anti-Pattern 04 (`no-sub-agent-dispatch`)** — honest caveat: dispatch saves the *lead's* context and improves fidelity via isolation, but *raises* total tokens (~4×/15×). — **ADR-036**.
+- **Anti-Pattern 03 (`single-monolithic-rule-file`)** — adds the fidelity axis (attention-budget / context-rot dilution, "minimal ≠ short", cache-vs-attention placement). — **ADR-036**.
+- **README brought to current 0.4.0 state** — tool-coverage matrix corrected to *tool-capability vs CONDUCTOR-emission* (all six tools ship hooks / sub-agents / model routing; only emission is Claude-only today — ADR-031); status line, recipe counts, and the self-improvement + token-economy features surfaced.
+- **Public-facing URLs** — README clone commands and `package.json` `repository` / `homepage` / `bugs` now point to the public repo (`omniconductor`) instead of the private working repo, so npm and public-README users get working links.
+
 ## [0.3.0] — 2026-07-05
 
 ### Added — Self-improvement / Reflector (opt-in, propose-only)

package/README.md

@@ -6,7 +6,11 @@ Write your project's rules, workflow, and discipline ONCE. Install into any AI c
 
 > Born from one year of production iteration at LFamily Labs — the rules, agents, hooks, and memory patterns that survived real shipping pressure.
 
-> **Status (v0.2.x — 2026-06-28)**: All 6 adapters now ship a working `transform.sh` — **Claude Code (full: rules + hooks + sub-agents)**, **Cursor (rules + lazy load)**, **GitHub Copilot (rules across 5 IDEs via single install)**, **Gemini CLI (`GEMINI.md` + `.gemini/styleguide.md`)**, **Codex (`AGENTS.md`)**, **Windsurf (`.windsurfrules` + `.devin/rules/*.md`)**. Output is emit-verified (format-validator + CI on all 6); live runtime consumption by Gemini / Codex / Windsurf is still adopter-pending — see [`docs/ADAPTER-LIVE-VERIFICATION.md`](./docs/ADAPTER-LIVE-VERIFICATION.md). Manual install in [`docs/MANUAL-INSTALL.md`](./docs/MANUAL-INSTALL.md) remains as a fallback. Marketplace listing (VSCode Marketplace + Open VSX) is **Phase 2 / v0.3+** — see ADR-023.
+> **Status (v0.4.0 — 2026-07-05)**: All 6 adapters ship a working `transform.sh` — **Claude Code** (full: rules + hooks + sub-agents + per-call model routing), **Cursor**, **GitHub Copilot** (one install covers 5 IDEs), **Gemini CLI** (`GEMINI.md` + `.gemini/styleguide.md`), **Codex** (`AGENTS.md`), **Windsurf / Devin Desktop** (`.windsurfrules` + `.devin/rules/*.md`). Published to npm as [`omniconductor`](https://www.npmjs.com/package/omniconductor) (v0.4.0). Output is emit-verified (format-validator + CI on all 6); live runtime consumption by Gemini / Codex / Windsurf is adopter-pending — see [`docs/ADAPTER-LIVE-VERIFICATION.md`](./docs/ADAPTER-LIVE-VERIFICATION.md). Manual install ([`docs/MANUAL-INSTALL.md`](./docs/MANUAL-INSTALL.md)) remains a fallback.
+>
+> **New in 0.4.0**: instruction-fidelity-first **token economy** — reduce tokens without distorting your instructions: lossless context editing before lossy compaction, an output-brevity discipline, and a new "verbose output" anti-pattern (ADR-035/036; [`docs/CONTEXT-EDITING-GUIDE.md`](./docs/CONTEXT-EDITING-GUIDE.md)). **In 0.3.0**: an opt-in **self-improvement / Reflector loop** (reads session trajectories + git and *proposes* lessons — propose-only — on all six tools; `--recipes=self-improvement`, ADR-030/032/033) + a first-party-verified **compatibility-matrix correction** (all six tools ship hooks / sub-agents / per-task model routing, retiring the old "Claude-only" view; ADR-031). Full history: [`CHANGELOG.md`](./CHANGELOG.md).
+>
+> Marketplace listing (VSCode Marketplace + Open VSX) remains **Phase 2** (post-0.4) — see ADR-023.
 
 ---
 
@@ -37,7 +41,7 @@ Write your project's rules, workflow, and discipline ONCE. Install into any AI c
 
 - **Layer 1 (`core/`) — Universal**: 도구 독립적인 워크플로 정의, 룰 텍스트, 문서 템플릿, 4-type 메모리 패턴
 - **Layer 2 (`adapters/<tool>/`) — Adapter**: `core/` 의 universal 자료를 각 도구의 네이티브 포맷으로 변환 (`.claude/` / `.cursor/rules/*.mdc` / `.github/instructions/*.instructions.md` / `GEMINI.md` / `AGENTS.md` / `.windsurfrules`)
-- **Layer 3 — Tool-native (정직한 한계)**: Sub-agent dispatch, hooks API, lazy-load 룰 같은 Claude 전용 기능은 다른 도구에서 재현하지 않고 정직하게 문서화
+- **Layer 3 — Tool-native (정직한 한계)**: 2026년 기준 6개 도구 모두 hooks·sub-agent·per-call model routing 을 **지원**한다 (ADR-031). 다만 CONDUCTOR 어댑터가 이를 실제로 **emit 하는 건 현재 Claude 뿐** (나머지는 Phase 2). "도구가 못 함"이 아니라 "CONDUCTOR emission gap" 임을 정직하게 문서화 — ADR-004 / ADR-031. (Windsurf 는 session/stop hook 이벤트가 없는 유일한 실제 예외.)
 
 ### 강제하는 워크플로
 
@@ -53,7 +57,7 @@ Write your project's rules, workflow, and discipline ONCE. Install into any AI c
 
 ```bash
 # 1. CONDUCTOR 클론
-git clone https://github.com/lee77840/conductor_lfamily ~/conductor
+git clone https://github.com/lee77840/omniconductor ~/conductor
 
 # 2. 적용할 프로젝트로 이동
 cd ~/your-project
@@ -84,7 +88,7 @@ Three layers:
 
 - **Layer 1 (`core/`) — Universal**: tool-agnostic workflow definitions, rule text, doc templates, 4-type memory pattern.
 - **Layer 2 (`adapters/<tool>/`) — Adapter**: per-tool transform script that reads `core/` and writes tool-native files.
-- **Layer 3 — Tool-native (honest limits)**: Claude-Code-only features (sub-agent dispatch, hooks API, per-call model routing) are NOT polyfilled on other tools. ADR-004 documents this honesty principle.
+- **Layer 3 — Tool-native (honest limits)**: as of 2026 **all six tools ship hooks, sub-agents, and per-call model routing** (ADR-031) — but CONDUCTOR's adapters currently *emit* them for **Claude only** (the rest is Phase 2). The honest limit is CONDUCTOR's emission gap, not a tool limitation, and nothing is fake-polyfilled. See ADR-004 / ADR-031. (Windsurf / Devin Desktop is the one real exception — no session/stop hook events.)
 
 ### Why this exists
 
@@ -105,7 +109,7 @@ Three layers:
 > Simplest (no clone): `npx omniconductor init --target=claude .` — the clone+bash steps below are equivalent.
 
 ```bash
-git clone https://github.com/lee77840/conductor_lfamily ~/conductor
+git clone https://github.com/lee77840/omniconductor ~/conductor
 cd ~/your-project
 bash ~/conductor/adapters/claude/transform.sh . \
   --recipes=monorepo,coding-conventions \
@@ -121,20 +125,27 @@ Other tools: see [Install paths](#install-paths). Windows: see [Cross-platform](
 
 ## Tool coverage matrix
 
-| Tool | Adapter | Rules | Hooks | Sub-agents | Model routing | Recommended install |
-|---|---|---|---|---|---|---|
-| **Claude Code** | ✅ Full (`adapters/claude/`) | ✅ lazy load | ✅ Stop / PreToolUse | ✅ 6 named agents | ✅ per-call `model:` | `bash adapters/claude/transform.sh <target>` |
-| **Cursor** | ✅ Full (`adapters/cursor/`) | ✅ lazy load (`.mdc` globs) | ❌ | ❌ rule reminder only | ❌ | `bash adapters/cursor/transform.sh <target>` |
-| **GitHub Copilot** | ✅ Full (`adapters/copilot/`) | ✅ `applyTo:` scoping | ❌ | ❌ | ❌ | `bash adapters/copilot/transform.sh <target>` — 1 install covers VSCode + Cursor + Windsurf + JetBrains + Neovim |
-| **Gemini CLI** | ✅ Full (`adapters/gemini/`) | ✅ single bundle (`GEMINI.md`) | ❌ | ❌ | ❌ | `bash adapters/gemini/transform.sh <target>` (+ `.gemini/styleguide.md` opt-in) |
-| **Codex (OpenAI)** | ✅ Full (`adapters/codex/`) | ✅ single bundle (`AGENTS.md`) | ❌ | ❌ | ❌ | `bash adapters/codex/transform.sh <target>` |
-| **Windsurf** | ✅ Full (`adapters/windsurf/`) | ✅ baseline (`.windsurfrules`) + `.devin/rules/*` | ❌ | ❌ | ❌ | `bash adapters/windsurf/transform.sh <target>` |
+Separate two things (per [`docs/COMPATIBILITY-MATRIX.md`](./docs/COMPATIBILITY-MATRIX.md), re-verified against first-party sources 2026-07-04, ADR-031):
 
-Full per-feature matrix: [`docs/COMPATIBILITY-MATRIX.md`](./docs/COMPATIBILITY-MATRIX.md).
+- **Tool capability** — as of 2026, **all six tools ship hooks, sub-agents, custom named agents, per-task model routing, and commands.** The old "these are Claude-only" view is out of date. (Windsurf / Devin Desktop is the one partial: it has hooks but no session/stop events.)
+- **CONDUCTOR emission** — what an adapter actually *compiles to today*. Claude emits the full set; every tool also emits the opt-in Reflector loop (ADR-032/033). Emitting the rest of the hook / agent set on the five non-Claude adapters is **Phase 2**.
 
-> **CLI wrapper**: `node bin/omniconductor.js init --target=<tool> <dir>` (and, once the package is published to npm, `npx omniconductor init --target=<tool> <dir>`) dispatches to these same adapter scripts — with `list`, `--dry-run`, `--recipes=`, and `--uninstall`.
+The columns below show **CONDUCTOR emission today** (⚠️ = the tool supports it, adapter emission is Phase 2 — a CONDUCTOR gap, not a tool limitation):
 
-> **What you keep going from Claude → other tools**: all rule text, all doc templates, the 4-type memory pattern, the workflow phase definitions. **What you lose**: auto-blocking hooks, per-call model routing, sub-agent dispatch. The discipline is portable; the enforcement is not.
+| Tool | Adapter (rules) | Hooks | Sub-agents | Model routing | Recommended install |
+|---|---|---|---|---|---|
+| **Claude Code** | ✅ Full, lazy load | ✅ emitted (Stop / PreToolUse) | ✅ emitted (6 named agents; 7 with `self-improvement`) | ✅ emitted (per-call `model:`) | `bash adapters/claude/transform.sh <target>` |
+| **Cursor** | ✅ Full, lazy load (`.mdc` globs) | ⚠️ tool ✅ · emit Phase 2 | ⚠️ tool ✅ · Claude-only by design (ADR-004) | ⚠️ tool ✅ · emit Phase 2 | `bash adapters/cursor/transform.sh <target>` |
+| **GitHub Copilot** | ✅ Full (`applyTo:` scoping) | ⚠️ tool ✅ · emit Phase 2 | ⚠️ tool ✅ · Claude-only by design | ⚠️ tool ✅ · emit Phase 2 | `bash adapters/copilot/transform.sh <target>` — 1 install covers VSCode + Cursor + Windsurf + JetBrains + Neovim |
+| **Gemini CLI** | ✅ Full (`GEMINI.md`) | ⚠️ tool ✅ · emit Phase 2 | ⚠️ tool ✅ · Claude-only by design | ⚠️ tool ✅ · emit Phase 2 | `bash adapters/gemini/transform.sh <target>` (+ `.gemini/styleguide.md` opt-in) |
+| **Codex (OpenAI)** | ✅ Full (`AGENTS.md`) | ⚠️ tool ✅ · emit Phase 2 | ⚠️ tool ✅ · Claude-only by design | ⚠️ tool ✅ · emit Phase 2 | `bash adapters/codex/transform.sh <target>` |
+| **Windsurf / Devin Desktop** | ✅ Full (`.windsurfrules` + `.devin/rules/*`) | ⚠️ partial (no session/stop events) · emit Phase 2 | ⚠️ tool ✅ (Devin Local) · Claude-only by design | ⚠️ tool ✅ · emit Phase 2 | `bash adapters/windsurf/transform.sh <target>` |
+
+Full per-feature matrix + first-party footnotes: [`docs/COMPATIBILITY-MATRIX.md`](./docs/COMPATIBILITY-MATRIX.md).
+
+> **CLI wrapper**: `npx omniconductor init --target=<tool> <dir>` (published to npm) — or `node bin/omniconductor.js init --target=<tool> <dir>` from a local clone — dispatches to these same adapter scripts, with `list`, `--dry-run`, `--recipes=`, and `--uninstall`.
+
+> **What you keep going Claude → other tools**: all rule text, doc templates, the 4-type memory pattern, the workflow phases, and the opt-in Reflector loop (emitted on all six). **What is still Claude-only in CONDUCTOR's *emission* today**: auto-blocking hooks, per-call model routing, sub-agent dispatch — a Phase-2 emission gap, **not** a tool limitation (the tools support them; Windsurf is the one real exception, for Stop-style hooks). The discipline is portable; the enforcement is becoming portable as adapter emission catches up.
 
 ---
 
@@ -165,7 +176,7 @@ Single command per tool. Adapter detects the target's existing state, runs an in
 #### Mac / Linux
 
 ```bash
-git clone https://github.com/lee77840/conductor_lfamily ~/conductor
+git clone https://github.com/lee77840/omniconductor ~/conductor
 cd ~/your-project
 
 # Pick your tool:
@@ -179,7 +190,7 @@ bash ~/conductor/adapters/copilot/transform.sh  . --recipes=monorepo,coding-conv
 ```bash
 # 1. Install Git for Windows: https://git-scm.com/download/win
 # 2. Open Git Bash terminal
-git clone https://github.com/lee77840/conductor_lfamily /c/conductor
+git clone https://github.com/lee77840/omniconductor /c/conductor
 cd /c/Users/me/Projects/my-app
 
 bash /c/conductor/adapters/claude/transform.sh . --recipes=monorepo,coding-conventions
@@ -192,7 +203,7 @@ bash /c/conductor/adapters/claude/transform.sh . --recipes=monorepo,coding-conve
 ```bash
 # Inside WSL2 Ubuntu — same commands as Mac/Linux
 wsl
-git clone https://github.com/lee77840/conductor_lfamily ~/conductor
+git clone https://github.com/lee77840/omniconductor ~/conductor
 cd ~/your-project
 bash ~/conductor/adapters/claude/transform.sh . --recipes=monorepo,coding-conventions
 ```
@@ -278,7 +289,7 @@ Want weekly session self-review? YES → self-improvement
 | Web + mobile (single language) | `web-mobile-parity, coding-conventions` |
 | Multi-locale SaaS | `i18n, coding-conventions` |
 | Monorepo SaaS | `monorepo, coding-conventions` |
-| Full-stack (monorepo + multi-locale + web/mobile) | All 10 |
+| Full-stack (monorepo + multi-locale + web/mobile) | `monorepo, i18n, web-mobile-parity, coding-conventions` |
 
 ---
 
@@ -291,7 +302,7 @@ Usage: bash adapters/<tool>/transform.sh <target-project> [options]
 | Option | Description |
 |---|---|
 | `<target-project>` | Project directory to install into (required). `.` for current dir. |
-| `--recipes=A,B,C` | Comma-separated recipes from the 10 in `core/recipes/`. |
+| `--recipes=A,B,C` | Comma-separated recipes from the 11 in `core/recipes/`. |
 | `--dry-run` | Preview only — no files written. |
 | `--measure-baseline` | Run `tools/measure-tokens.sh --latest` after install; save CSV; auto-show anti-patterns if cache hit < 95%. |
 | `--no-prompt` | Skip wizard, apply defaults (CI-safe). Combine with `--recipes` and `--measure-baseline` as needed. |
@@ -300,7 +311,7 @@ Usage: bash adapters/<tool>/transform.sh <target-project> [options]
 | `--force` | Bypass uninstall safety gates (active rebase/merge, missing manifest). |
 | `-h` `--help` | Print usage. |
 
-**Recipe names**: `web-mobile-parity`, `i18n`, `monorepo`, `branch-strategy`, `auto-mock-data`, `coding-conventions`, `tdd`, `debugging`, `database-discipline`, `design-system`.
+**Recipe names** (11): `web-mobile-parity`, `i18n`, `monorepo`, `branch-strategy`, `auto-mock-data`, `coding-conventions`, `tdd`, `debugging`, `database-discipline`, `design-system`, `self-improvement`.
 
 #### File overwrite behavior
 
@@ -399,7 +410,7 @@ diff CLAUDE.md.conductor-backup-* CLAUDE.md
 
 #### "recipe not found" warning
 
-Check recipe name spelling. Available: `web-mobile-parity`, `i18n`, `monorepo`, `branch-strategy`, `auto-mock-data`, `coding-conventions`, `tdd`, `debugging`, `database-discipline`, `design-system`.
+Check recipe name spelling. Available: `web-mobile-parity`, `i18n`, `monorepo`, `branch-strategy`, `auto-mock-data`, `coding-conventions`, `tdd`, `debugging`, `database-discipline`, `design-system`, `self-improvement`.
 
 #### "Tool doesn't recognize the new rules"
 
@@ -413,7 +424,7 @@ chmod +x .claude/hooks/*.sh  # grant if missing
 # Restart Claude Code
 ```
 
-Hooks are a Claude-Code-only feature.
+All six tools now ship hooks (Windsurf / Devin Desktop is partial — no session/stop events; ADR-031). CONDUCTOR *emits* hook configs for **Claude only** today (non-Claude hook emission is Phase 2), so the files under `.claude/hooks/` are Claude-specific — but hooks as a capability are not.
 
 #### "Disable one hook"
 
@@ -448,7 +459,7 @@ Claude Code uses `~/.claude/projects/.../memory/`; other tools use `docs/memory/
 
 #### Architecture Decision Records (`docs/DESIGN-DECISIONS.md`)
 
-28 ADRs cover the foundational decisions. Highlights:
+36 ADRs cover the foundational decisions. Highlights:
 
 | ADR | Topic | Why it matters |
 |---|---|---|
@@ -460,17 +471,21 @@ Claude Code uses `~/.claude/projects/.../memory/`; other tools use `docs/memory/
 | **ADR-020** | `--uninstall` + manifest tracking | Why install is reversible |
 | **ADR-021** | Cursor adapter (`adapters/cursor/transform.sh`) | Adapter design for `.cursor/rules/*.mdc` |
 | **ADR-022** | Copilot adapter (single-format, 5-IDE coverage) | Why one Copilot install covers VSCode + Cursor + Windsurf + JetBrains + Neovim |
-| **ADR-023** | Marketplace strategy + cross-platform | Phase 1 (now: bash) → Phase 2 (v0.3+: VSCode extension) |
+| **ADR-023** | Marketplace strategy + cross-platform | Phase 1 (now: bash + npm) → Phase 2 (post-0.3: VSCode extension) |
+| **ADR-030** | Self-improvement is opt-in, propose-only | Nothing learns silently — the Reflector proposes, you approve |
+| **ADR-035/036** | Instruction-fidelity-first token economy | Reduce tokens without distorting your instructions (context editing, output brevity, `docs/CONTEXT-EDITING-GUIDE.md`) |
 
 Full list and bodies: [`docs/DESIGN-DECISIONS.md`](./docs/DESIGN-DECISIONS.md).
 
+**What changed between versions:** see [`CHANGELOG.md`](./CHANGELOG.md) — every release and its Added / Changed entries, newest first.
+
 ---
 
 ## FAQ
 
 **Q: Why no marketplace install today?**
 
-A: ADR-023 — the bash adapter is the validated source of truth. A marketplace extension is Phase 2 / v0.3+; the wrapper depends on the adapter being stable in adopter projects first.
+A: ADR-023 — the bash adapter is the validated source of truth. A marketplace extension is Phase 2 (post-0.3); the wrapper depends on the adapter being stable in adopter projects first.
 
 **Q: Cursor adopters — do I install from VSCode Marketplace or Open VSX?**
 
@@ -478,7 +493,7 @@ A: Open VSX. Cursor is a VSCode fork but cannot pull from Microsoft's marketplac
 
 **Q: My project uses Go / Python / Rust, not TypeScript.**
 
-A: Skip `coding-conventions` (TypeScript-specific). The 5 universal rule bundles and the other 9 recipes are stack-agnostic.
+A: Skip `coding-conventions` (TypeScript-specific). The 5 universal rule bundles and the other 10 recipes are stack-agnostic.
 
 **Q: Windows native PowerShell?**
 

package/core/anti-patterns/README.md

@@ -8,6 +8,7 @@ linked_rules:
   - workflow (W2 docs-first, W4 7-step)
 linked_docs:
   - docs/PROMPT-CACHING-GUIDE.md
+  - docs/CONTEXT-EDITING-GUIDE.md
   - docs/KPI.md
 ---
 
@@ -28,6 +29,7 @@ CONDUCTOR's universal rules describe the *correct* patterns. This catalog descri
 | 05 | [Frequent rule-file edits](frequent-rule-file-edit.md) | MEDIUM | -20% to -40% / week | > 3 rule-file commits per week |
 | 06 | [Tool-call spam](tool-call-spam.md) | MEDIUM | latency + output spike | tool calls / turn > 1.5 |
 | 07 | [Skill / MCP eager-load](skill-eager-load.md) | MEDIUM | prefix bloat, hidden multipliers | 30+ eager skills or broad path triggers |
+| 08 | [Verbose output / narration](output-verbosity-narration.md) | MEDIUM | output-cost, not cache-hit | output tokens/turn > 1200 with few tool calls |
 
 Severity legend (estimated impact on cache hit rate, derived from Anthropic prompt-caching cost model + P1.5 baseline):
 - **HIGH** ≈ -50% or more
@@ -51,7 +53,7 @@ When efficiency feels off — costs creeping up, latency climbing, sessions gett
    |---|---|---|
    | Cache hit rate | ≥ 95% | < 90% — start at Anti-Pattern 01 |
    | Tool calls / turn | ≤ 0.8 | > 1.2 — start at Anti-Pattern 06 |
-   | Output tokens / turn | ≤ 800 | > 1200 — Anti-Pattern 04 + 06 likely |
+   | Output tokens / turn | ≤ 800 | > 1200 — Anti-Pattern 04 + 06 + 08 likely |
    | Cache-write / session | ≤ 30M | > 50M — Anti-Pattern 02 + 03 + 07 likely |
    | Dispatches / session | 30-150 | 0 on a multi-feature session — Anti-Pattern 04 |
 
@@ -62,7 +64,7 @@ When efficiency feels off — costs creeping up, latency climbing, sessions gett
    | Cache hit rate dropped this week, no other change | 01, 05 |
    | Session JSONL ballooning past 100MB | 02, 04, 07 |
    | Latency creeping per turn over the session | 02, 04 |
-   | High output cost on apparently simple tasks | 04, 06 |
+   | High output cost on apparently simple tasks | 04, 06, 08 |
    | First-turn cost (before user types anything) is large | 03, 07 |
    | Cache hit rate fine inside session but resets each new session | 05 |
 
@@ -76,6 +78,7 @@ When efficiency feels off — costs creeping up, latency climbing, sessions gett
 - **CONDUCTOR P1.5 baseline** (`docs/KPI.md`, 2026-05-07) — 8 sessions on a single active project, 100% cache hit rate ceiling, avg 0.61 tool calls / turn, avg 27.4M cache-write / session.
 - **`core/universal-rules/meta-discipline.md` §5** — token economy rules (Read discipline, hidden injection, dispatch budget, cache-friendly prompt order, tool description compression, touched-file rule scoping).
 - **`docs/PROMPT-CACHING-GUIDE.md`** — full Claude-adapter caching guide.
+- **`docs/CONTEXT-EDITING-GUIDE.md`** — instruction-fidelity-first context reduction (lossless `clear_tool_uses` before lossy `/compact`).
 
 The reference project measured in `KPI.md` is one specific monorepo (the originating workspace). Numbers in catalog entries are *estimates anchored to that baseline*. Other projects will see different absolute numbers but the same *direction* — the anti-patterns degrade efficiency on every codebase.
 
@@ -115,6 +118,7 @@ CONDUCTOR universal rules가 *옳은* 패턴을 기술한다면, 이 카탈로
 | 05 | [잦은 룰 파일 수정](frequent-rule-file-edit.md) | MEDIUM | 주당 -20% ~ -40% | 주 3회 이상 룰 파일 commit |
 | 06 | [tool-call 스팸](tool-call-spam.md) | MEDIUM | latency + output 폭증 | tool calls / turn > 1.5 |
 | 07 | [Skill / MCP eager-load](skill-eager-load.md) | MEDIUM | prefix bloat, 숨은 multiplier | eager skill 30개 초과 또는 광범위 path trigger |
+| 08 | [장황한 출력 / 나레이션](output-verbosity-narration.md) | MEDIUM | cache-hit 아닌 output 비용 | tool call 적은데 output tokens/turn > 1200 |
 
 ## 진단 워크플로 (요약)
 

package/core/anti-patterns/no-sub-agent-dispatch.md

@@ -47,6 +47,15 @@ Without dispatch:
 
 **Reference data** (Conductor P1.5 baseline): the two largest sessions (219MB + 187MB) both contained heavy in-thread work; smaller sessions with active dispatch use stayed under 70MB. Avg dispatches/session = 104.6. The recommended P2 target is -25% dispatch *frequency* (batch related work) but the *anti-pattern* of zero dispatch is far more costly than over-dispatch.
 
+### 2.1 Honest caveat — dispatch saves the *lead's* context, not the *total* token bill
+
+Dispatch is a **context-isolation** win, not a raw total-token saver. Anthropic's own multi-agent reporting is explicit: single agents use ~4× the tokens of a chat interaction, and multi-agent systems ~15× — because every dispatched agent runs its own context window and reasoning. What dispatch buys is:
+
+- a **lean leader context** (only the 0.5–2K summary returns, so the cacheable main thread stays small), and
+- **higher fidelity** (the verbose intermediate state that would dilute the leader's attention budget stays quarantined in the sub-agent).
+
+So dispatch when the *value of isolation* (a clean leader + focused attention) exceeds the *added total token cost* — i.e. verbose, self-contained subtasks. Do NOT dispatch work that needs the leader's full shared context or has tight back-and-forth dependencies: there the coordination overhead and duplicated context make a single thread both cheaper and more faithful. (Anthropic: tasks requiring "all agents to share the same context" or with "many dependencies between agents" are a poor fit; "most coding tasks involve fewer truly parallelizable tasks than research.")
+
 ## 3. Detection
 
 **Quantitative**:

package/core/anti-patterns/output-verbosity-narration.md

@@ -0,0 +1,72 @@
+---
+anti_pattern_id: output-verbosity-narration
+name: "Verbose output / narration — the model over-explains every turn"
+type: anti-pattern
+severity: MEDIUM
+hit_rate_impact: "output-cost, not cache-hit: output tokens priced ~5× input"
+detection_method:
+  - measure-tokens (output tokens / turn vs KPI baseline)
+  - eyeball: preamble + restating the ask + re-printed file bodies
+applies_to: ["all-tools"]
+linked_rules:
+  - meta-discipline (5.9 output brevity)
+---
+
+# Anti-Pattern 08 — Verbose output / narration
+
+## 1. What it is
+
+The model spends output tokens on prose that carries no information the user needs: preamble ("Great question! Let me take a look…"), restating the request back, narrating each step before doing it, re-printing whole file bodies after an edit, and a long recap at the end. The *work* may be correct and efficient; the *response describing it* is 3–5× longer than the task warrants.
+
+```
+# WRONG — 900-token answer to a one-line question
+"That's a great question! Let me think through this carefully. First, I want to
+make sure I understand what you're asking. You'd like me to rename the variable
+`x` to `count`. Let me explain my approach before I begin. I'll start by locating
+every usage… [200 more tokens] … Here is the full updated file: [entire 180-line
+file re-printed] … To summarize what I did above, I renamed the variable…"
+```
+
+Unlike Anti-Pattern 06 (tool-call spam), which is about too many *tool calls*, this is about too much *generated prose* — it can spike even on a turn with zero tool calls.
+
+## 2. Why it costs
+
+- **Output is the expensive token.** Across the current lineup output is priced ~5× input (e.g. Opus 4.8 $5 in / $25 out per MTok). A turn that could answer in 150 output tokens but spends 900 costs 6× more on the priciest side of the meter.
+- **It compounds into input next turn.** Every verbose response becomes conversation history that is re-read (cache-read, but still billed) on every subsequent turn until compaction. Bloated output today is bloated input for the rest of the session.
+- **Re-printed file bodies are the worst offender** — a single re-printed 180-line file after an edit can be 2K+ output tokens that the Edit tool already captured for free.
+
+Conductor's P1.5 baseline targets output tokens / turn ≤ 800; investigate above ~1200.
+
+## 3. Detection
+
+**Quantitative**:
+```bash
+bash tools/measure-tokens.sh --latest | grep -E 'output tokens'
+```
+- Output tokens / turn > 1200 sustained → red flag (KPI healthy ≤ 800).
+- High output cost on turns with 0–1 tool calls → prose bloat, not tool bloat (distinguishes from Anti-Pattern 06).
+
+**Eyeball signals**: responses that open with preamble, restate the user's request, re-print a file the model just edited, or close with a recap of what was said one screen up.
+
+## 4. Fix / Alternative
+
+**Per `meta-discipline.md` §5.9 (output brevity)**:
+
+- **Answer first, no preamble/postamble.** Lead with the result; cut "Great question", "Let me…", and end-of-turn recaps.
+- **Don't restate the ask.** The user knows what they asked.
+- **Reference edits, don't reprint them.** After an Edit, say *what* changed and *where* (`file:line`) — the diff already exists; the file body does not need to re-enter the output stream.
+- **Right-size the format.** One line for a one-line question; reserve tables/numbered steps for genuinely multi-part work.
+- **Cap bounded artifacts** with `max_tokens` (Claude adapter) when the ceiling is known.
+
+**Fidelity guard** (per §5.9): brevity trims prose, never substance. Keep every warning, caveat, failing-test result, or action the user must take. When forced to choose, completeness beats brevity.
+
+## 5. Severity rating
+
+**MEDIUM** — rarely session-breaking on its own, but a steady tax on every turn and the easiest anti-pattern to fix (it costs nothing to stop over-explaining). Worst when combined with re-printed file bodies on edit-heavy sessions.
+
+| Response style | Output tokens / turn | Verdict |
+|---|---|---|
+| Answer-first, edits by reference | 100–400 | optimal |
+| Some narration, occasional recap | 500–800 | acceptable |
+| Preamble + restate + recap | 900–1400 | trim |
+| Re-prints full files after edits | 1500+ | refactor habit |

package/core/anti-patterns/single-monolithic-rule-file.md

@@ -41,7 +41,14 @@ The file IS cacheable, so cache hit rate stays high. The damage is on a differen
 
 Conductor's P1.5 baseline shows avg cache-write per session = 27.4M tokens. The P2 target is -30% (to ~19M) — most of that reduction comes from splitting the monolithic file.
 
-## 3. Detection
+### 2.1 The second axis — it also degrades fidelity, not just cost
+
+Cache-write is the measurable cost. The subtler damage is to **instruction fidelity**. Every token in the window draws down a finite *attention budget*; Anthropic's context-engineering guidance is explicit that "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases" (context rot). A 1,800-line rule file carrying 1,400 lines irrelevant to the current task doesn't just cost more — it **dilutes the model's attention across noise**, making it measurably likelier to miss or misapply the rules that *do* matter this turn.
+
+Two corollaries:
+
+- **"Minimal" ≠ "short".** The target is "the smallest set of *high-signal* tokens" — a complete rule stated once beats an exhaustive rule stated three times. Trim redundancy and irrelevance, not necessary substance.
+- **Placement note (fidelity vs cache tension).** Prompt caching wants stable content (rules, CLAUDE.md) *first* in the prefix for cache-prefix matching (`PROMPT-CACHING-GUIDE.md`). Long-context recall, meanwhile, is strongest at the very start and very end and weakest in the middle ("lost in the middle"). These don't conflict if the prefix stays lean: the active per-turn instruction is the user's latest message, which already sits at the end. But a bloated rule prefix pushes the genuinely-relevant scoped rules into the low-attention middle — another reason to path-scope (§4) rather than pile everything into one always-loaded file.
 
 ```bash
 # Find oversized rule files

package/core/anti-patterns/skill-eager-load.md

@@ -65,7 +65,7 @@ In a 50-Read session those modifiers alone account for 10-30K tokens of cache-wr
 
 2. **Path-scoped auto-injection** (per `meta-discipline.md` §5.6): when a tool offers path-triggered skills, ensure the path glob is *narrow*. The reference project pays for `<web-app>/app/**` triggering 3 skills because that glob is broad. Narrowing to `<web-app>/app/api/**/route.ts` (Next.js route handlers only) reduces trigger frequency by ~80%.
 
-3. **MCP gateway / lazy-load proxy**: when many MCP servers are registered, route them through a lazy-loading proxy so only the tool *names* enter the prefix, with full schemas fetched on first use. Reference: `meta-discipline.md` §5.5.
+3. **Deferred tool loading** (per `meta-discipline.md` §5.5): when many tools / MCP servers are registered, load only tool *names* into the prefix and fetch full schemas on first use. On the Claude API this is the **Tool Search Tool** — set `defer_loading: true` per tool or on an `mcp_toolset`; Anthropic reports "over 85%" reduction in tool-definition context while preserving the prompt cache (a typical five-server MCP setup otherwise costs ~55K tokens in definitions before any work). At least one tool must stay non-deferred. Where no such API exists, route MCP servers through a lazy-loading gateway proxy to the same effect.
 
 **Conductor's deferred-tool pattern**: this session uses `ToolSearch` to fetch tool schemas only when needed. That is the canonical example — tool names are visible in system reminders, but invoking a tool requires fetching its schema first. The same principle generalizes to skills.
 

package/core/universal-rules/meta-discipline.md

@@ -180,26 +180,60 @@ Full guide: the CONDUCTOR repo's `docs/PROMPT-CACHING-GUIDE.md` (not installed i
 
 ### 5.5 Tool description compression
 
-When > 30 tools are loaded, the description footprint becomes a measurable cost. Use deferred / lazy-loaded tool patterns where supported.
+Tool schemas (names, descriptions, JSON Schemas) are billed as input tokens on **every** request, plus a small per-model tool-use system prompt. A typical multi-MCP setup (e.g. a code host + a chat platform + an error tracker + a couple of observability servers) can consume ~55K tokens in definitions before any work begins.
+
+When many tools are loaded, use **deferred / lazy tool loading** so only tool *names* enter the prefix and full schemas are fetched on first use:
+
+- **Claude API**: the Tool Search Tool (`defer_loading: true` per tool, or on an `mcp_toolset`) — Anthropic reports "over 85%" reduction in tool-definition context while preserving the prompt cache. At least one tool must stay non-deferred.
+- **This session** already demonstrates the pattern via `ToolSearch`: tool names appear in system reminders, but invoking one requires fetching its schema first.
+
+See Anti-Pattern 07 (skill / MCP eager-load).
 
 ### 5.6 Touched-file rule scoping
 
 Use `paths:` (Claude) / `globs:` (Cursor) / `applyTo:` (Copilot) to scope rule files to the source areas they govern. A rule that fires only when a relevant file is touched is cheaper than a rule loaded into every turn.
 
-### 5.7 Auto-compact threshold
+### 5.7 Context reduction WITHOUT instruction loss
+
+When the window fills, there are two ways to free budget — and they are NOT equal on fidelity. The orchestrator MUST prefer the lossless one.
+
+- **Lossless (preferred) — drop stale tool results, not user turns.** Old tool outputs (file reads, command output, search hits) are the bulk of a bloated window and carry near-zero forward value once acted on. Clearing them frees budget without touching a single user instruction. On the Claude adapter this is the API context-editing feature (`clear_tool_uses`): it clears tool results / thinking blocks only and **never** user instructions or text messages. See `docs/CONTEXT-EDITING-GUIDE.md`.
+- **Lossy (last resort) — summarizing older turns.** Summarization / compaction (`/compact`, auto-compact near the window cap) compresses **everything, including the user's own turns**, so it can silently drop or distort the original instruction. Use only after lossless clearing is exhausted.
+
+**Compaction safeguards (mandatory whenever lossy compaction runs):**
+
+1. Keep durable instructions in the always-loaded rule / context file (CLAUDE.md / project rules), not in conversation history — they survive compaction because they are re-loaded every turn.
+2. When you must compact, pass explicit preservation instructions (e.g. `/compact keep the original task statement, acceptance criteria, and open TODOs verbatim`).
+3. Between unrelated tasks, prefer a full reset (`/clear`) over letting the window bloat and then lossily compacting.
+4. After any compaction, re-verify the compacted note still carries the original instruction before continuing. If in doubt, ask the user to restate — never proceed on a possibly-distorted summary.
 
-When the conversation context approaches the model's window cap, summarize older turns into a compact note and free the budget. Some tools auto-compact at ~80%; others rely on the orchestrator to trigger it.
+Rationale: raw token count is a finite **attention budget**, and the goal is the *smallest set of high-signal tokens* — but never at the cost of the user's original intent. Stale tool results are the first thing to cut; user instructions are the last.
 
 ### 5.8 .ignorefile maintenance
 
 Each tool has its own ignore file (`.claudeignore`, `.cursorignore`, `.aiderignore`, etc.). Keep these in sync — they prevent expensive accidental Reads of build outputs, large lockfiles, or vendored code.
 
+### 5.9 Output brevity (output tokens cost ~5× input)
+
+Output tokens are priced far higher than input — roughly 5× across the current lineup (e.g. Opus 4.8 is $5 in / $25 out per MTok). The orchestrator's own responses are a directly controllable cost:
+
+- **Answer, don't narrate.** Skip preamble ("Great question! Let me…"), postamble, and restating what the user already said. Lead with the result.
+- **Match verbosity to the task.** A one-line answer for a one-line question; reserve tables and step-by-steps for genuinely multi-part work.
+- **Don't echo file bodies back.** After an edit, state what changed by reference — do not re-print the file.
+- **Cap bounded artifacts.** Use `max_tokens` (Claude adapter) when the expected output has a known ceiling.
+
+**Fidelity guard:** brevity trims *the model's prose*, never *required substance*. Do not drop a warning, a caveat, a failing-test result, or a step the user must act on in the name of being terse. When forced to choose, completeness beats brevity. (This trade-off caveat is CONDUCTOR discipline, not an Anthropic-documented rule.)
+
+See Anti-Pattern 08 (verbose output / narration).
+
 ---
 
 ## 6. Model Routing (M3)
 
 The orchestrator classifies every task and selects model tier explicitly. The user does NOT specify the model per request — that responsibility belongs to the orchestrator.
 
+> **Lineup / pricing snapshot** (verified 2026-07, $ per MTok input / output): Haiku 4.5 **$1 / $5** · Sonnet 5 **$3 / $15** · Opus 4.8 **$5 / $25** · Fable 5 **$10 / $50**. Output is ~5× input at every tier (see §5.9). The tier labels below are generation-agnostic on purpose — prices and model names drift, so re-verify against Anthropic's pricing page before quoting.
+
 ### 6.1 Tier 1 — Conceptual / complex (Opus-tier)
 
 Trigger if any of:
@@ -231,7 +265,9 @@ Trigger if any of:
 
 ### 6.4 Override rule of thumb
 
-> When in doubt, **upgrade one tier**. Cost difference is modest; risk of Sonnet misinterpreting conceptual work is large.
+> When in doubt, **upgrade one tier**. Cost difference is modest; risk of a weaker model misinterpreting conceptual work is large.
+
+This is a **fidelity** rule, not only cost caution. Anthropic's own tool-use guidance notes that on a missing required parameter, Opus "is much more likely to recognize a parameter is missing and ask," whereas a cheaper model "might also infer a reasonable value" — i.e. guess. On conceptual or instruction-dense work, a guess is instruction distortion. Route by fidelity risk, not by token price alone.
 
 ### 6.5 Surface the choice
 

package/core/universal-rules/spec-as-you-go.md

@@ -63,7 +63,19 @@ When work is committed and pushed, the orchestrator MUST update the following do
 
 When a task in CURRENT_WORK.md or TASKS.md is moved to status `completed`, it should be DELETED in the next session boundary, not left as historical clutter. The session log itself is the historical record. CURRENT_WORK.md is for what is current, not what was done last week. (Full rule: `operations.md` section 2.)
 
-### 2.2 What the orchestrator does NOT update
+### 2.2 Referenced-fact currency — update EVERY place a changed fact lives
+
+When a change alters a fact that other docs also state — a count ("7 anti-patterns"), an enumerated list (a catalog index, a table of files / recipes / tiers), a version or price, a cross-reference, or a renamed path — the same-turn sync includes **every** doc that repeats that fact, not only the file you edited. A value that is true in one file and stale in three others is a documentation bug; the reader trusts whichever file they open first, so a half-updated fact is worse than an obviously-old one.
+
+The mechanic (before declaring the turn complete):
+
+1. **Grep for the old value** — the old count, the removed name, the renamed path. Every hit is a candidate to update, or to *consciously* leave (e.g. a dated historical milestone entry, which stays as a record).
+2. **If the change has no home, give it one.** A new decision / mechanism / guarantee that no existing doc states must be recorded: extend the most relevant doc, or CREATE a new one and register it in `docs/INDEX.md`. A change that is real but unrecorded is not done.
+3. **Architectural decisions additionally get an ADR** (`meta-discipline.md` R5 → `docs/DESIGN-DECISIONS.md`).
+
+Documented failure (this project): a catalog grew from 7 to 8 entries; the catalog's own index was updated but `CLAUDE.md`, `docs/INDEX.md`, and the changelog kept saying "7". Each was individually plausible and collectively wrong.
+
+### 2.3 What the orchestrator does NOT update
 
 - Session transcripts / chat exports — those are tool-specific and out of scope.
 - External tracker tickets (Jira / Linear / GitHub Issues) — those are explicit user actions, not auto-sync.

package/docs/CONTEXT-EDITING-GUIDE.md

@@ -0,0 +1,58 @@
+# Context Editing Guide (Claude / Anthropic SDK)
+
+> Per ADR-035, CONDUCTOR's Claude adapter recommends **API context editing** as the *lossless-first* way to reduce context tokens without losing the user's instructions. This guide describes the mechanism, the fidelity guarantee, and the safeguards for the lossy fallback (`/compact`). Like prompt caching (`docs/PROMPT-CACHING-GUIDE.md`), context editing is an Anthropic-SDK-side concern — CONDUCTOR provides discipline and ordering, not boilerplate code.
+>
+> **Scope:** Claude API / Claude Code only. The five non-Claude adapters degrade to the rule text in `meta-discipline.md` §5.7. See the parity note at the end.
+
+## Why this exists — the fidelity axis
+
+Every token in the window depletes a finite **attention budget**, and as the window grows the model's ability to recall any single item decreases ("context rot"). So reducing context is genuinely valuable — but the naive reducer (summarize old turns) compresses the *user's own instructions* along with everything else, silently dropping or distorting the original intent.
+
+The core rule: **cut stale tool output first; touch user instructions last.** Tool results (file reads, command output, search hits) are the bulk of a bloated window and carry near-zero forward value once acted on. Clearing them frees most of the budget while leaving every user turn intact.
+
+## The two reducers, ranked by fidelity
+
+| Reducer | What it removes | Instruction fidelity | When to use |
+|---|---|---|---|
+| **API context editing** (`clear_tool_uses`) | Stale tool **results** (and optionally tool inputs / thinking blocks) | **Preserved** — user instructions and text messages are never cleared | **Default.** Long tool-heavy sessions. |
+| **`/compact`** (Claude Code) | Summarizes **all** older history, user turns included | **At risk** — lossy summarization can drop or distort the original ask | Last resort, with the safeguards below. |
+| **`/clear`** (Claude Code) | Wipes the entire context | N/A (intentional full reset) | Between *unrelated* tasks. |
+
+### Verified mechanics (primary sources)
+
+**API context editing** — Anthropic Messages API, public beta (verified 2026-07):
+- Beta header: `context-management-2025-06-27`. Strategy id: `clear_tool_uses_20250919`.
+- **Clears** stale tool *results*; optionally tool *inputs* (`clear_tool_inputs: true`, default `false`) and thinking blocks (`clear_thinking_20251015`). Cleared results are replaced with placeholder text.
+- **Never clears** user instructions or text messages — editing targets tool results / thinking only.
+- Defaults: `trigger` = 100,000 input tokens; `keep` = 3 most-recent tool-use/result pairs. `clear_at_least` and `exclude_tools` are optional knobs.
+- Applied **server-side** before the prompt reaches the model; the client keeps the full history. ZDR-eligible.
+- Measured savings: doc example 70k → 25k tokens (~45k freed); an Anthropic 100-turn web-search eval reported **~84% token reduction**. Paired with the **memory tool** (file-based state that persists *outside* the window, same beta header), Anthropic reported **+39%** on their eval vs baseline (context editing alone **+29%**).
+- Source: <https://platform.claude.com/docs/en/build-with-claude/context-editing> · <https://claude.com/blog/context-management>
+
+**`/compact` vs `/clear`** — Claude Code (verified 2026-07):
+- Auto-compaction summarizes conversation history when "approaching context limits" (exact % trigger is **not** documented). It preserves architectural decisions / unresolved bugs / implementation details and discards redundant tool output — but it is a *lossy* summary of everything, including your turns.
+- Preservation levers: (a) `/compact <instructions>` — e.g. `/compact Focus on code samples and API usage`; (b) a `# Compact instructions` section in the project **CLAUDE.md** telling Claude what to preserve across every compaction.
+- `/clear` starts fresh (full wipe); `/compact` compresses and continues.
+- Source: <https://code.claude.com/docs/en/costs>
+
+## Recommended discipline (what the orchestrator does)
+
+1. **Default to lossless.** On the Claude API adapter, enable context editing (`clear_tool_uses`) so stale tool results are cleared automatically at the token trigger. This alone removes most window bloat without any risk to instructions.
+2. **Protect against tool-input loss where inputs matter.** Leave `clear_tool_inputs` at its default (`false`), or list tools whose call arguments must be retained under `exclude_tools`.
+3. **Keep durable instructions out of chat history.** Put anything that must survive the whole session in CLAUDE.md / project rules — it is re-loaded each turn and is unaffected by both compaction and context editing.
+4. **If lossy compaction is unavoidable**, pass explicit preservation instructions (`/compact keep the original task statement, acceptance criteria, and open TODOs verbatim`) and/or maintain a `# Compact instructions` block in CLAUDE.md.
+5. **Reset, don't bloat.** Between unrelated tasks, `/clear` beats letting the window fill and then lossily compacting.
+6. **Re-verify after compaction.** Confirm the compacted note still carries the original instruction before continuing; if unsure, ask the user to restate rather than act on a possibly-distorted summary.
+
+## Interaction with prompt caching
+
+Context editing modifies the message body **below** the cached rule/CLAUDE.md prefix, so it does not touch the stable cache prefix described in `PROMPT-CACHING-GUIDE.md`. The two techniques compose: caching cuts the cost of the stable prefix; context editing cuts the size of the volatile tail. Note that clearing tool results changes the suffix, which is expected — the cache breakpoint sits above it.
+
+## Per-tool parity (honest)
+
+| Tool | Lossless tool-result clearing | Compaction levers |
+|---|---|---|
+| Claude Code / Claude API | **Yes** — `clear_tool_uses` + memory tool | `/compact <instr>`, `# Compact instructions`, `/clear` |
+| Cursor / Copilot / Gemini / Codex / Windsurf | No equivalent API feature — falls back to `meta-discipline.md` §5.7 rule text (drop stale reads, keep instructions in the rules file, reset between tasks) | Tool-native reset only |
+
+The honest summary: the *principle* (cut stale tool output first, never the user's instructions) is universal and lives in `meta-discipline.md` §5.7; the *lossless mechanism* is Claude-API-only today.

package/docs/PROMPT-CACHING-GUIDE.md

@@ -0,0 +1,111 @@
+# Prompt Caching Guide (Claude / Anthropic SDK)
+
+> Per ADR-012, CONDUCTOR's Claude adapter actively recommends prompt caching. This guide describes the recommended structure. Caching is an Anthropic-SDK-side concern — CONDUCTOR provides structure and order, not boilerplate code.
+
+## Why prompt caching matters
+
+Anthropic's prompt caching reduces input cost by ~90% and latency by ~85% for prefixes that repeat across turns. Cache write is 1.25× input cost (5-min cache) or 2× (1-hr cache). Cache read is 0.1× input cost. Break-even after 2-3 reads.
+
+For a typical CONDUCTOR-driven session:
+- 5 universal rule bundles (~6K tokens combined).
+- Project CLAUDE.md (~2K tokens).
+- Selected recipes (~1-3K tokens).
+- Project memory index (~1K tokens).
+
+Total cacheable prefix: ~10-12K tokens. Without caching, 10-12K input tokens are billed every turn. With a 60% hit rate, the effective cost drops to ~1-1.5K tokens per turn.
+
+## Recommended prefix order
+
+Order matters: Anthropic prefix-matches from the START of the prompt. Items that change less frequently must come first.
+
+```
+[1. Universal rules]              ← changes rarely (one CONDUCTOR upgrade per quarter)
+   - .claude/rules/workflow.md
+   - .claude/rules/spec-as-you-go.md
+   - .claude/rules/quality-gates.md
+   - .claude/rules/operations.md
+   - .claude/rules/meta-discipline.md
+
+[2. Project CLAUDE.md]            ← changes occasionally (project rule additions)
+
+[3. Selected recipes]             ← changes when adopter installs / removes recipe
+   - .claude/rules/<recipe>.md (per --recipes flag)
+
+[4. Project memory index]         ← changes weekly (new feedback / project entries)
+
+══════ cache_control: {"type": "ephemeral"} ══════
+
+[5. CURRENT_WORK.md content]      ← changes per turn
+[6. Recent turn history]          ← changes per turn
+[7. Tool results]                 ← per turn
+[8. User's new message]           ← per turn
+```
+
+The `cache_control` marker is placed at the boundary between sections 4 and 5. Everything above is cacheable; everything below is the per-turn variable content.
+
+## Anthropic SDK example
+
+The exact API call shape depends on the SDK version. Conceptually:
+
+```python
+client.messages.create(
+    model="claude-opus-4-7-20260101",
+    system=[
+        # cacheable section
+        {
+            "type": "text",
+            "text": load_universal_rules() + load_claude_md() + load_recipes() + load_memory_index(),
+            "cache_control": {"type": "ephemeral"}
+        }
+    ],
+    messages=[
+        # per-turn section
+        {"role": "user", "content": user_message}
+    ]
+)
+```
+
+The orchestrator's responsibility is to ASSEMBLE the cacheable prefix in stable order. If the order shuffles between turns, the cache misses.
+
+## 5-min vs 1-hr cache
+
+| TTL | Write cost | When to use |
+|---|---|---|
+| 5 min (default) | 1.25× input | Active dev session — turns within 5 min of each other |
+| 1 hr | 2× input | Long-running sessions, tool integrations, agent loops |
+
+For CONDUCTOR's typical use (interactive dev session), 5-min default is correct. The break-even on the 1-hr cache requires 8+ turns within the hour.
+
+## Measuring cache hit rate
+
+Use the bundled tool:
+
+```bash
+tools/measure-tokens.sh --latest
+```
+
+Sample output:
+```
+Cache-read tokens            : 9847
+Cache hit rate               : 67.3%
+```
+
+Target: ≥ 60% on a steady-state dev session. If the rate is lower:
+
+- Verify the cache marker is at the right boundary.
+- Verify prefix order is stable (no per-turn re-ordering of CONDUCTOR rules).
+- Verify the prefix is large enough to clear the model's minimum cache size (1024 tokens for Opus / Sonnet, 2048 for Haiku).
+
+## Common cache misses
+
+| Cause | Fix |
+|---|---|
+| Prefix too short | Combine universal rules + recipes into a single system block |
+| Prefix order changes per turn | Stabilize the build order |
+| New recipe installed mid-session | Expected one-time miss; subsequent turns hit |
+| Memory index regenerated each turn | Re-generate only when memory dir changes |
+| Model switch (Opus ↔ Sonnet ↔ Haiku) | Each model has its own cache; switching invalidates |
+
+## Non-Claude tools
+
+Prompt caching is an Anthropic-specific feature. Other adapters (Cursor / Copilot / Gemini / Codex / Windsurf) cannot benefit from this guide. The `docs/COMPATIBILITY-MATRIX.md` records this honestly.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "omniconductor",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Multi-coding-agent workflow framework. Write your project's rules, workflow, and discipline ONCE — install into Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, or Windsurf. Encodes the discipline developers most often skip — spec-before-code, review gates, session continuity — so your AI agents catch what's easy to miss.",
   "license": "Apache-2.0",
   "author": "LFamily Labs LLC",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lee77840/conductor_lfamily.git"
+    "url": "git+https://github.com/lee77840/omniconductor.git"
   },
-  "homepage": "https://github.com/lee77840/conductor_lfamily#readme",
+  "homepage": "https://github.com/lee77840/omniconductor#readme",
   "bugs": {
-    "url": "https://github.com/lee77840/conductor_lfamily/issues"
+    "url": "https://github.com/lee77840/omniconductor/issues"
   },
   "engines": {
     "node": ">=18"
@@ -24,6 +24,8 @@
     "core/",
     "tools/",
     "docs/MANUAL-INSTALL.md",
+    "docs/PROMPT-CACHING-GUIDE.md",
+    "docs/CONTEXT-EDITING-GUIDE.md",
     "README.md",
     "VISION.md",
     "LICENSE",