omniconductor 0.3.0

package/bin/omniconductor.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * omniconductor — thin dispatcher to the per-tool adapter transform scripts.
+ *
+ * Usage:
+ *   omniconductor init --target=<tool> [target-dir] [--recipes=a,b] [--dry-run] [--no-prompt]
+ *   omniconductor init --target=<tool> [target-dir] --uninstall [--force]
+ *   omniconductor list
+ *   omniconductor --help | --version
+ *
+ * It does NOT reimplement any install logic. It locates this repo's
+ * adapters/<tool>/transform.sh and runs it with `bash`, forwarding all flags
+ * and inheriting stdio. The shell adapters remain the single source of truth
+ * (ADR-018 / the bash adapters are the validated implementation).
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const TOOLS = ['claude', 'cursor', 'copilot', 'gemini', 'codex', 'windsurf'];
+
+function readVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function usage() {
+  return `omniconductor ${readVersion()} — install CONDUCTOR's workflow into an AI coding tool
+
+Usage:
+  omniconductor init --target=<tool> [target-dir] [options]   Install into target-dir (default: .)
+  omniconductor list                                          List available tool adapters
+  omniconductor --help | --version
+
+Tools: ${TOOLS.join(', ')}
+
+Common options (forwarded to the adapter):
+  --recipes=a,b,c     Opt-in recipes to install
+  --dry-run           Preview only — write nothing
+  --no-prompt         Skip interactive prompts (CI-safe)
+  --uninstall         Revert a previous install (manifest-based)
+  --force             Bypass uninstall safety checks
+
+Examples:
+  omniconductor init --target=claude ./my-app --recipes=tdd,debugging
+  omniconductor init --target=cursor ./my-app --dry-run
+  omniconductor init --target=codex . --uninstall
+
+Run:  npx omniconductor init --target=<tool> <dir>`;
+}
+
+function fail(msg) {
+  process.stderr.write(`omniconductor: ${msg}\n\n`);
+  process.stderr.write(usage() + '\n');
+  process.exit(2);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(usage() + '\n');
+    return 0;
+  }
+  if (args.includes('--version') || args.includes('-v')) {
+    process.stdout.write(readVersion() + '\n');
+    return 0;
+  }
+
+  const cmd = args[0];
+
+  if (cmd === 'list') {
+    process.stdout.write('Available adapters:\n');
+    for (const t of TOOLS) {
+      const present = fs.existsSync(path.join(ROOT, 'adapters', t, 'transform.sh'));
+      process.stdout.write(`  ${t.padEnd(9)} ${present ? '✅ transform.sh' : '⏳ not implemented'}\n`);
+    }
+    return 0;
+  }
+
+  if (cmd !== 'init') {
+    fail(`unknown command '${cmd}'. Expected 'init' or 'list'.`);
+  }
+
+  // Parse `init` args: extract --target, the positional target-dir, forward the rest.
+  let target = null;
+  let targetDir = null;
+  const passthrough = [];
+  for (const a of args.slice(1)) {
+    if (a.startsWith('--target=')) {
+      target = a.slice('--target='.length);
+    } else if (a === '--target') {
+      fail('use --target=<tool> (with =), e.g. --target=claude');
+    } else if (a.startsWith('-')) {
+      passthrough.push(a);
+    } else if (targetDir === null) {
+      targetDir = a;
+    } else {
+      passthrough.push(a);
+    }
+  }
+
+  if (!target) fail('missing --target=<tool>');
+  if (!TOOLS.includes(target)) fail(`unknown target '${target}'. One of: ${TOOLS.join(', ')}`);
+
+  const transform = path.join(ROOT, 'adapters', target, 'transform.sh');
+  if (!fs.existsSync(transform)) {
+    fail(`the '${target}' adapter has no transform.sh yet (manual install — see docs/MANUAL-INSTALL.md).`);
+  }
+
+  const dir = targetDir || '.';
+  const cmdline = ['bash', transform, dir, ...passthrough];
+  process.stderr.write(`omniconductor → ${cmdline.slice(1).join(' ')}\n`);
+
+  const res = spawnSync('bash', [transform, dir, ...passthrough], { stdio: 'inherit' });
+  if (res.error) {
+    process.stderr.write(`omniconductor: failed to run adapter: ${res.error.message}\n`);
+    return 1;
+  }
+  return res.status === null ? 1 : res.status;
+}
+
+process.exit(main(process.argv));

package/core/README.md

@@ -0,0 +1,64 @@
+# `core/` — Layer 1, Universal source-of-truth
+
+Anything in this directory MUST work for every supported tool. No tool-specific syntax, no `.claude/` references, no Cursor `.mdc` directives, no Copilot `applyTo:` annotations.
+
+## What lives here
+
+| Subdirectory | Purpose |
+|---|---|
+| `workflow/` | The Plan → Architecture → Tasks → Implementation → Review → Spec phase definitions. Tool-agnostic phase boundaries. |
+| `universal-rules/` | The 5 universal rules (operations, coding-conventions, token-economy, spec-as-you-go, model-routing). Each is plain markdown. |
+| `docs-templates/` | The doc skeletons every project gets (`CURRENT_WORK.md`, `REMAINING_TASKS.md`, `PLANS.md`, `TASKS.md`, `INDEX.md`, `specs/_example.md`). |
+| `memory-pattern/` | Documentation of the 4-type memory pattern (user / feedback / project / reference). NOT actual memory data. |
+
+## Authoring conventions
+
+### Plain markdown only
+
+ATX headings, tables for comparisons, fenced code blocks with language hint. No HTML. No tool-specific syntax.
+
+### Front-matter is OPTIONAL and routing-only
+
+If a rule needs adapter routing hints (e.g., "this rule applies only to TypeScript files"), use minimal YAML front-matter that adapters can transform:
+
+```markdown
+---
+applies_to:
+  - "**/*.ts"
+  - "**/*.tsx"
+tier: T1   # informational; how prominent in always-loaded baseline
+---
+
+# Rule body in plain markdown
+```
+
+Adapters translate `applies_to:` to:
+- Claude: `paths:` in the rule's front-matter
+- Cursor: `globs:` in `.mdc`
+- Copilot: `applyTo:` in `.instructions.md`
+- Gemini / Codex / Windsurf: bundled (no per-pattern routing)
+
+### No tool-specific examples
+
+If you cite an example, make it generic. ❌ "use `Agent` tool to dispatch". ✅ "delegate to a specialized agent persona".
+
+If a rule HAS to reference a Claude-only mechanism, put the example under a clearly-labeled tool-native callout that adapters can show or hide:
+
+```markdown
+> **Claude-only mechanism**: enforced via Stop hook (`stop-session-log-check.sh`).
+> Other tools: rely on rule reminder + manual discipline.
+```
+
+## Status (P0 foundation)
+
+All files in subdirectories are PLACEHOLDERS describing intent. P1 fills them with real content sanitized from the reference adopter.
+
+## Adapter contract (referenced, not implemented here)
+
+Each adapter MUST:
+- Read every file under `core/`.
+- Translate front-matter to the target tool's format.
+- Emit at the conventional path for that tool (see `docs/HOW-IT-WORKS-PER-TOOL.md`).
+- Never modify files in `core/`.
+
+See `adapters/README.md` for the full adapter contract.

package/core/anti-patterns/README.md

@@ -0,0 +1,142 @@
+---
+catalog_id: anti-patterns
+description: "Token-economy anti-pattern catalog — diagnostic reference for adopters losing cache hit rate, paying for tool spam, or carrying bloated prefixes."
+type: catalog
+applies_to: ["all-tools"]
+linked_rules:
+  - meta-discipline (token economy section)
+  - workflow (W2 docs-first, W4 7-step)
+linked_docs:
+  - docs/PROMPT-CACHING-GUIDE.md
+  - docs/KPI.md
+---
+
+# `core/anti-patterns/` — Token-economy anti-pattern catalog
+
+> What goes wrong when CONDUCTOR is installed without discipline. Each entry is grounded in the Anthropic prompt-caching cost model and the P1.5 baseline measurements (`docs/KPI.md`, 2026-05-07).
+
+CONDUCTOR's universal rules describe the *correct* patterns. This catalog describes the **wrong** ones — what they look like, why they damage token efficiency, how to detect them, and the fix. Adopters who follow the universal rules avoid these by construction; the catalog exists for diagnostic use when efficiency drops.
+
+## Index
+
+| # | Anti-Pattern | Severity | Hit-rate impact | Detection signal |
+|---|---|---|---|---|
+| 01 | [Dynamic system prompt](dynamic-system-prompt.md) | HIGH | -50% to -90% | hit rate < 30% with stable prefix size |
+| 02 | [Large-file Read without range](large-file-read-no-range.md) | HIGH | indirect bloat | full-file Read on > 200-line files |
+| 03 | [Single monolithic rule file](single-monolithic-rule-file.md) | HIGH | direct cache-write bloat | rule file > 500 lines, no path scoping |
+| 04 | [No sub-agent dispatch](no-sub-agent-dispatch.md) | MEDIUM | indirect main-thread bloat | dispatches/session = 0 on multi-feature work |
+| 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 |
+
+Severity legend (estimated impact on cache hit rate, derived from Anthropic prompt-caching cost model + P1.5 baseline):
+- **HIGH** ≈ -50% or more
+- **MEDIUM** ≈ -20%
+- **LOW** ≈ -10% (none in the current catalog; reserved for future entries)
+
+## Diagnostic workflow
+
+When efficiency feels off — costs creeping up, latency climbing, sessions getting bloated — run the catalog end-to-end:
+
+1. **Measure the current state.**
+   ```bash
+   cd <conductor-repo>
+   bash tools/measure-tokens.sh --latest
+   ```
+   Note the four numbers: cache hit rate, tool calls/turn, output tokens/turn, cache-write/session.
+
+2. **Compare to baseline** (`docs/KPI.md` P1.5):
+
+   | Metric | Healthy | Investigate when |
+   |---|---|---|
+   | 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 |
+   | Cache-write / session | ≤ 30M | > 50M — Anti-Pattern 02 + 03 + 07 likely |
+   | Dispatches / session | 30-150 | 0 on a multi-feature session — Anti-Pattern 04 |
+
+3. **Match the symptom → catalog entry**.
+
+   | Symptom | Suspected anti-pattern(s) |
+   |---|---|
+   | 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 |
+   | First-turn cost (before user types anything) is large | 03, 07 |
+   | Cache hit rate fine inside session but resets each new session | 05 |
+
+4. **Read the matching catalog entry's §3 Detection + §4 Fix.** Apply the fix; re-measure after one full session.
+
+5. **If multiple anti-patterns apply**, address them in severity order (HIGH → MEDIUM). The HIGH entries are usually 80% of the cost.
+
+## Reference points cited across this catalog
+
+- **Anthropic prompt caching docs** — cost model (cache-write 1.25× / 2×, cache-read 0.1×, prefix-match-only).
+- **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.
+
+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.
+
+## What is NOT in this catalog
+
+- **Code-correctness anti-patterns** (silent failures, type-design issues) — those live in role-specific reviewer guidance, not in token-economy rules.
+- **Workflow anti-patterns** (skipping reviews, batching unsafe edits) — those are in `core/universal-rules/workflow.md` and `quality-gates.md`.
+- **Tool-specific quirks** (Cursor-only, Copilot-only) — those live in `adapters/<tool>/`.
+
+This catalog is exclusively about how an installation degrades the **token economy** layer of CONDUCTOR.
+
+## Contributing new entries
+
+A new catalog entry is justified when:
+
+1. The pattern has been observed in production (cite the session / project).
+2. The cost model is quantifiable (Anthropic pricing or measure-tokens output).
+3. The fix references an existing universal-rule or recipe — not a new ad-hoc rule.
+4. Severity is honestly assessed against the rubric in this README.
+
+File template: copy any existing entry; preserve the frontmatter schema; keep the file ≤ 200 lines.
+
+---
+
+# `core/anti-patterns/` — 토큰 경제 안티패턴 카탈로그 (한글 요약)
+
+CONDUCTOR universal rules가 *옳은* 패턴을 기술한다면, 이 카탈로그는 **그 반대** — 무엇이 잘못되는가, 왜 토큰 효율을 망가뜨리는가, 어떻게 감지하고 어떻게 고치는가 — 를 기록한다. universal-rules 를 따르면 이 안티패턴들은 자연스럽게 회피된다. 이 카탈로그는 효율이 떨어졌을 때 *진단용* 으로 사용한다.
+
+## 카탈로그 인덱스
+
+| # | 안티패턴 | 심각도 | hit-rate 영향 | 감지 시그널 |
+|---|---|---|---|---|
+| 01 | [동적 system prompt](dynamic-system-prompt.md) | HIGH | -50% ~ -90% | prefix 크기는 안정인데 hit rate < 30% |
+| 02 | [범위 없는 대형 파일 Read](large-file-read-no-range.md) | HIGH | 간접 bloat | 200줄 이상 파일 전체 Read |
+| 03 | [단일 거대 룰 파일](single-monolithic-rule-file.md) | HIGH | 직접적인 cache-write 폭증 | 룰 파일 500줄 초과 + path 스코프 미사용 |
+| 04 | [sub-agent dispatch 미사용](no-sub-agent-dispatch.md) | MEDIUM | main thread 누적 bloat | 멀티-피처 세션인데 dispatch = 0 |
+| 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 |
+
+## 진단 워크플로 (요약)
+
+1. `bash tools/measure-tokens.sh --latest` 실행 → cache hit rate / tool calls per turn / output tokens per turn / cache-write per session 4개 수치 확인.
+2. `docs/KPI.md` P1.5 baseline 과 비교 — 어느 수치가 빠졌는지 파악.
+3. 위 인덱스의 "감지 시그널" 컬럼으로 의심 안티패턴 매칭.
+4. 해당 카탈로그 항목의 §3 (Detection) + §4 (Fix / Alternative) 읽고 적용.
+5. 한 세션 분량 작업 후 다시 측정. HIGH 부터 처리하면 보통 비용의 80% 가 잡힌다.
+
+## 카탈로그에 포함되지 *않는* 것
+
+- 코드 정확성 안티패턴 (silent failure, type design 문제) — reviewer role guidance 영역.
+- 워크플로 안티패턴 (review skip, 위험한 batch edit) — `core/universal-rules/workflow.md`, `quality-gates.md` 영역.
+- Tool 별 quirk — `adapters/<tool>/` 영역.
+
+이 카탈로그는 오직 **토큰 경제** 레이어에서 일어나는 효율 저하만 다룬다.
+
+## 새 항목 추가 기준
+
+1. 실제 운영 중 관찰된 패턴 (세션 / 프로젝트 인용).
+2. 비용이 정량화 가능 (Anthropic pricing 또는 measure-tokens 출력 기반).
+3. 해결책이 기존 universal-rule / recipe 를 참조 — 새 ad-hoc 룰 만들지 않을 것.
+4. 심각도는 README 의 기준표에 솔직하게 평가.
+
+파일 템플릿: 기존 항목 복사. frontmatter 스키마 유지. 200줄 이하 유지.

package/core/anti-patterns/dynamic-system-prompt.md

@@ -0,0 +1,113 @@
+---
+anti_pattern_id: dynamic-system-prompt
+name: "Dynamic system prompt — per-turn injection of volatile state"
+type: anti-pattern
+severity: HIGH
+hit_rate_impact: "-50% to -90%"
+detection_method:
+  - measure-tokens (cache hit rate < 30% with stable prefix size)
+  - grep for `Date.now()` / timestamp templating in system-prompt builder
+applies_to: ["all-tools-with-prompt-caching"]
+linked_rules:
+  - meta-discipline (5.4 cache-friendly prompt order)
+  - reference: docs/PROMPT-CACHING-GUIDE.md
+---
+
+# Anti-Pattern 01 — Dynamic System Prompt
+
+## 1. What it is
+
+The orchestrator builds the system prompt fresh on every turn, with volatile content (current timestamp, session ID, last-edit time, transient state) interleaved with the stable rule body.
+
+```python
+# WRONG — invalidates cache every single turn
+system = f"""
+Today is {datetime.now().isoformat()}.
+You have {get_unread_messages()} unread messages.
+Last edited file: {last_edited_path}.
+
+[universal rules ...]
+[CLAUDE.md ...]
+"""
+```
+
+Anything before the cache_control marker is part of the prefix that Anthropic prefix-matches from byte 0. A single character that changes per turn invalidates everything after it.
+
+## 2. Why it kills cache
+
+Anthropic prompt caching is **prefix-match-only**. The first byte that differs between two turns is the cache miss point. Everything after — even if textually identical — must be re-written.
+
+Cost model (Anthropic prompt caching docs):
+- Cache write = 1.25× input cost (5-min) or 2× (1-hr)
+- Cache read = 0.1× input cost
+- Break-even after 2-3 reads
+
+If a 12K-token prefix is invalidated every turn:
+- Per-turn billed input = 12K × 1.25 = 15K cache-write equivalent
+- Vs cached: 12K × 0.1 = 1.2K cache-read
+- **Cost multiplier: ~12.5× per turn**
+
+For a 100-turn session: 1.5M extra input tokens vs the cached baseline.
+
+## 3. Detection
+
+**Quantitative signal** (`tools/measure-tokens.sh`):
+- Cache hit rate < 30% despite a large stable rule body
+- Cache-write tokens roughly equal to cache-read tokens (write-heavy session)
+
+**Code-level signal** (grep over orchestrator harness):
+```bash
+grep -RIE 'Date|now\(\)|timestamp|uuid|random|process\.uptime' \
+  --include='*.{ts,js,py}' src/orchestrator/
+```
+
+**Reference baseline**: Conductor's measured baseline (P1.5, 2026-05-07) shows 100% hit rate across 8 sessions of an active dev project, because the system prompt is stable. Any drop from that ceiling deserves investigation.
+
+## 4. Fix / Alternative
+
+**Move volatile state below the cache_control boundary.** The cacheable prefix only contains low-frequency content; per-turn state goes into the user message section.
+
+```python
+# RIGHT
+system = [
+    {
+        "type": "text",
+        "text": load_universal_rules() + load_project_md() + load_recipes(),
+        "cache_control": {"type": "ephemeral"}
+    }
+]
+messages = [
+    {
+        "role": "user",
+        "content": (
+            f"Current time: {datetime.now().isoformat()}\n"
+            f"Last edited: {last_edited_path}\n"
+            f"---\n{user_message}"
+        )
+    }
+]
+```
+
+Per `core/universal-rules/meta-discipline.md` §5.4, the order is:
+
+```
+[1] Universal rules (lowest change rate)
+[2] Project rules
+[3] Selected recipes
+[4] Memory index
+══ cache_control: ephemeral ══
+[5] Per-turn state, tool results, user message
+```
+
+The Conductor reference project keeps `currentDate` as a system-reminder tag injected by the harness AFTER the cache boundary — not inside the rule body — which is the correct pattern.
+
+## 5. Severity rating
+
+**HIGH** — single biggest cache-invalidator. A 5-minute investigation usually reveals one or two volatile fields that, once moved below the boundary, restore hit rate from <30% to >80%.
+
+| Symptom | Hit-rate hit | Detection difficulty |
+|---|---|---|
+| Timestamp at top of system | -90% | trivial (grep) |
+| User-name template variable | -50% | medium |
+| Hash of last commit | -90% | medium |
+| Memory index regenerated each turn | -40% | medium |

package/core/anti-patterns/frequent-rule-file-edit.md

@@ -0,0 +1,83 @@
+---
+anti_pattern_id: frequent-rule-file-edit
+name: "Frequent rule-file edits — invalidating the cache prefix every session"
+type: anti-pattern
+severity: MEDIUM
+hit_rate_impact: "-20% to -40% over a working week"
+detection_method:
+  - git log on rule files (commits per week to CLAUDE.md / universal rules)
+  - measure-tokens cache-write delta across consecutive sessions
+applies_to: ["all-tools-with-prompt-caching"]
+linked_rules:
+  - workflow (W2 docs-first)
+  - meta-discipline (5.4 cache-friendly prompt order)
+---
+
+# Anti-Pattern 05 — Frequent rule-file edits
+
+## 1. What it is
+
+The project's main rule file (CLAUDE.md / AGENT.md / GEMINI.md / equivalent) — i.e. the file at the **top of the cache prefix** — is edited multiple times per week. Every edit, no matter how small, invalidates the cache for the next session that reloads it.
+
+```
+# WRONG — every other day:
+git log --oneline -- CLAUDE.md
+ab12cd3 docs(claude): tweak workflow phrasing
+de45f67 docs(claude): add new helper agent description
+89ab012 docs(claude): fix typo in section 4
+3456cde docs(claude): inline new troubleshooting tip
+```
+
+Each commit produces a different prefix bytes-wise, so the next session that loads the rule file pays the full cache-write again.
+
+## 2. Why it kills cache
+
+Anthropic prompt caching is **prefix-match**. The cache key is the byte sequence of the prefix. A single typo fix changes the byte sequence and the cache must be re-written.
+
+Cost model:
+- 5-min cache TTL → applies within a single session, robust to rule edits inside that session
+- Cross-session cache reuse depends on prefix byte-identity from the previous session
+
+Edit frequency vs hit rate (estimated, derived from Anthropic prompt caching docs cost model):
+
+| Edits/week to top-of-prefix file | Cross-session prefix reuse | Estimated hit-rate hit |
+|---|---|---|
+| 0 (stable) | full | 0% |
+| 1 | mostly, occasional miss | -10% |
+| 3 | partial, frequent miss | -25% |
+| 5+ | nearly always missed | -40% |
+
+If the rule file is edited daily, every session starts with a fresh cache write — a 30K-token write for the prefix alone, costing 1.25× input baseline.
+
+## 3. Detection
+
+```bash
+# Edits per week to top-of-prefix files
+git log --since='1 week ago' --pretty=format:'%h %s' -- \
+  CLAUDE.md AGENT.md GEMINI.md .codex/codex.md \
+  .claude/rules/*.md .cursor/rules/*.mdc 2>/dev/null | wc -l
+
+# Anything > 3 in a week is suspect
+```
+
+**Symptom in measure-tokens output**: cache-write tokens / session stays high across multiple sessions even when conversation length is short. A stable rule file shows declining cache-write/turn as the session ages; an edited rule file resets that decline every session.
+
+## 4. Fix / Alternative
+
+**Three disciplines** (compounding):
+
+1. **Batch edits.** Accumulate rule changes over a few days, then commit one consolidated update. Reference project policy: docs-only changes wait until the next code-bearing push (per `feedback_push_timing` in the originating project's memory).
+
+2. **Move volatile content downward.** New ad-hoc reminders, post-mortems, "watch out for X" notes belong in `CURRENT_WORK.md` (per-turn area, BELOW the cache boundary), not in the rule file.
+
+3. **Split paths-scoped from always-loaded.** When new content is path-relevant (e.g. "billing pitfalls"), put it in a path-scoped rule file (Anti-Pattern 03 fix), not the always-loaded floor.
+
+**Conductor's own policy** (per `core/universal-rules/README.md`): the 5 universal-rule bundles change "rarely (one CONDUCTOR upgrade per quarter)". Project-specific rules go in `core/recipes/` (opt-in). The recipe layer is intentionally below the universal-rule layer in the cache prefix order, so recipe edits invalidate less.
+
+**Reference**: `docs/PROMPT-CACHING-GUIDE.md` "Common cache misses" table lists "Prefix order changes per turn" — same root cause as frequent edits.
+
+## 5. Severity rating
+
+**MEDIUM** — the harm is gradual rather than per-turn catastrophic. A team that edits the rule file once a week loses ~10% hit rate; a team that edits it daily loses 30-40%. The cumulative cost over a quarter is significant but rarely visible in any single session.
+
+The fix is cheap: discipline + batch.

package/core/anti-patterns/large-file-read-no-range.md

@@ -0,0 +1,90 @@
+---
+anti_pattern_id: large-file-read-no-range
+name: "Whole-file Read on large files — no offset / limit"
+type: anti-pattern
+severity: HIGH
+hit_rate_impact: "indirect: cache-write inflation, output-token spike"
+detection_method:
+  - measure-tokens (cache-write tokens / session > 30M)
+  - session JSONL inspection (Read tool calls without offset/limit on files > 200 lines)
+applies_to: ["all-tools-with-file-Read"]
+linked_rules:
+  - meta-discipline (5.1 read discipline)
+  - reference: token-economy Read rule
+---
+
+# Anti-Pattern 02 — Large-file Read without range
+
+## 1. What it is
+
+The orchestrator (or a role agent) calls `Read` on a multi-hundred-line file without `offset` / `limit` parameters, pulling the entire file into context when only a small section is relevant.
+
+```
+# WRONG — pulls 2K+ lines into context to find one constant
+Read(file_path="<web-app>/lib/i18n/translations.ts")  # 2,400 lines
+
+# WRONG — re-Read the same large file in a later turn for a different key
+Read(file_path="<web-app>/lib/i18n/translations.ts")  # again
+
+# WRONG — scanning a long config to confirm a single value exists
+Read(file_path=".env.example")  # 180 lines, then again, then again
+```
+
+A single 2K-line Read can dump 20K-40K tokens into the context. Across a session of 50 such Reads, that is 1-2M tokens of cache-write churn.
+
+## 2. Why it kills cache
+
+The file content itself enters the conversation history. Once it is in the history, it sits inside the cache prefix for subsequent turns until the conversation rolls over. This means:
+
+- **Cache-write inflation**: every Read multiplies the size of the per-turn cacheable suffix.
+- **Hidden-skill amplifier**: certain paths auto-inject companion skills (next-cache-components, react-best-practices, framework docs) — 200-600 tokens hidden cost per Read. See `meta-discipline.md` §5.2.
+- **Output-token spike**: when the model summarizes or quotes the file, output cost rises proportionally to file size.
+
+Cost estimate (Anthropic pricing reference):
+- 50 full-file Reads × 30K tokens = 1.5M tokens of context bloat
+- At Sonnet output rate (~$15/M) the *response* tokens about that file alone can hit $20+ over a session.
+
+**Reference-adopter P1.5 measurement**: average tool calls per turn = 0.61. The two largest sessions had 7K-8K tool calls. If even 10% were full-file Reads on files > 500 lines, that is the root cause of multi-MB session JSONLs.
+
+## 3. Detection
+
+**Session-level**:
+```bash
+# Find Read tool calls without offset/limit on files known to be > 200 lines
+grep -E '"name":"Read".*"file_path":"[^"]+\.(ts|tsx|md|sql|json)"' \
+  ~/.claude/projects/<project>/<session>.jsonl | \
+  grep -v '"offset"' | wc -l
+```
+
+**Symptom**: cache-write tokens / session climb over 30M (Conductor baseline avg = 27.4M; sessions over that ceiling often have a Read-discipline gap).
+
+**Self-check (LLM)**: before any Read, ask "do I need 50+ contiguous lines, or am I after one symbol?" If the latter, Grep wins.
+
+## 4. Fix / Alternative
+
+**Two-step pattern: Grep first, then range-Read** (per `meta-discipline.md` §5.1):
+
+```
+# RIGHT
+Grep(pattern="MAX_RETRIES", path="<web-app>/lib/", output_mode="content", -n=true, -C=3)
+
+# Then, only if Grep showed the symbol exists and you need surrounding context:
+Read(file_path="<web-app>/lib/config.ts", offset=120, limit=50)
+```
+
+**Range-read defaults**:
+- For files > 200 lines: `offset` + `limit: 100` is mandatory.
+- Read more only if the first range proved insufficient.
+
+**Reference project pattern**: the originating workspace's `token-economy.md` rule explicitly forbids `cat` on a whole spec/CLAUDE.md/translations file. The framework version of that rule lives in `core/universal-rules/meta-discipline.md` §5.1.
+
+## 5. Severity rating
+
+**HIGH** — the largest single contributor to context bloat in production sessions. Combined with auto-injected skills (Anti-Pattern 07), a single careless Read can cost 1K+ tokens.
+
+| Pattern | Per-Read token cost | Per-session impact |
+|---|---|---|
+| Grep first, no Read needed | ~50 (Grep result) | minimal |
+| Range Read (limit=100) | ~1.5K | acceptable |
+| Full file Read on 500-line file | ~6K + auto-inject 600 | bloat |
+| Full file Read on 2K-line file | ~25K + auto-inject 600 | severe |