# Documentation Contradictions Report — 2026-06-27

**Scope:** All agent-directive markdowns (`AGENTS.md`, `conductor/*.md`, `conductor/code_styleguides/*.md`, `docs/*.md`) cross-referenced for logical soundness.

**Method:** Read all 14 styleguides + all 8 conductor root files + all 38 docs/*.md files end-to-end, then grep'd/selected specific claims against `src/*.py` and `scripts/*.py` to verify code-state alignment.

**Total contradictions found: 21** across 8 categories.

---

## Severity Legend

| Level | Meaning |
|---|---|
| 🔴 **CRITICAL** | Misleads agents into violating a Core Value mandate or running broken code |
| 🟠 **HIGH** | Contradicts an active spec/plan or causes agents to make wrong decisions |
| 🟡 **MEDIUM** | Drift between doc and code; mostly harmless but creates noise |
| 🟢 **LOW** | Doc tidiness; doesn't change agent behavior |

---

## Category 1: Mandatory Convention Enforcement Gaps 🔴🟠

These are the highest-impact contradictions: they make the Core Value mandate (2026-06-25) appear enforceable when it isn't.

### C1 — `Optional[T]` audit script name vs behavior 🟠

**Claim:** `conductor/code_styleguides/error_handling.md:212` says "Hard Rules (enforced in the 3 refactored files)". `docs/AGENTS.md` §"Convention Enforcement" says audit scripts run pre-commit. `error_handling.md:885` says the rule applies to "the 3 refactored files".

**Reality:**
- `scripts/audit_optional_in_3_files.py:24-29` defines `BASELINE_FILES = ("src/mcp_client.py", "src/ai_client.py", "src/rag_engine.py", "src/code_path_audit.py")` — **4 files**, not 3.
- The script is named `audit_optional_in_3_files.py` but covers 4. Internal contradiction between filename and behavior.
- The script has not been "extended to all `src/*.py` per the c11_python track" as `docs/AGENTS.md` claims.

**Fix:** Rename to `audit_optional_in_baseline_files.py` AND either (a) update `BASELINE_FILES` to actually be all `src/*.py` OR (b) update the docs to accurately reflect that the enforcement is only on 4 baseline files. The `cruft_elimination_20260627` spec says all 14 migration-target files should also be migrated, but there's no enforcement.

### C2 — Optional[T] ban scope ambiguity in docs 🟠

**Claim 1:** `conductor/code_styleguides/error_handling.md:212-222` says "Optional[T] return types are FORBIDDEN in the 3 refactored files" (mcp_client, ai_client, rag_engine).

**Claim 2:** `docs/AGENTS.md` §"Convention Enforcement" says "`scripts/audit_optional_in_3_files.py --strict` (extended to all `src/*.py` per the c11_python track)".

**Claim 3:** `conductor/tracks/cruft_elimination_20260627/state.toml:18` says Phase 6 (`Optional[T]` returns, 30 sites across 14 files) is "deferred".

**Contradiction:** The docs claim enforcement "extended to all src/*.py", but the audit script still only checks 4 files. The `cruft_elimination_20260627` spec says 30 sites remain across 14 untracked files — those are NOT enforced. An agent reading the docs would think the rule is global; in practice it's only enforced on 4 files.

**Fix:** Either (a) actually extend the audit script + rename it OR (b) clarify the docs: ban is enforced on baseline 4 files; cruft_elimination is the migration track for the remaining 14.

### C3 — Banned-pattern audit script "planned" but never built 🟠

**Claim:** `conductor/code_styleguides/python.md:413` says "The static analysis script `scripts/audit_imports.py` (planned) flags local imports outside `try/except ImportError` blocks."

**Reality:** `scripts/audit_imports.py` does NOT exist (verified via `ls scripts/audit_imports.py`). The 7-banned-pattern mandate has only 4 enforcement scripts (audit_weak_types, audit_optional_in_3_files, audit_exception_handling, generate_type_registry), not 5.

**Fix:** Either (a) build the script OR (b) remove the "planned" reference from `python.md`. The mandate has a gap: local imports + `_PREFIX` aliasing are policy without enforcement.

### C4 — Tier 2 pre-commit enforcement is sandbox-only 🟡

**Claim:** `docs/AGENTS.md` §"The pre-commit workflow" says "run before claiming 'done': uv run python scripts/audit_*.py [...] In CI / pre-commit hook" — implying pre-commit hooks exist.

**Reality:** Only `conductor/tier2/githooks/pre-commit` exists (per `tier2_leak_prevention_20260620`). There is no pre-commit hook in the main repo's `.git/hooks/`. The 4 audits listed are only enforced inside the Tier 2 sandbox.

**Fix:** Either (a) install the audits as actual pre-commit hooks in the main repo OR (b) clarify that the convention is enforced in Tier 2 sandbox only; the main repo relies on agent discipline + manual runs.

---

## Category 2: Doc vs Code State Drift 🟠🟡

### C5 — `Result[T, ErrorInfo]` notation is wrong 🟠

**Claim:** `docs/guide_ai_client.md:452` says all 8 vendors "return `Result[str, ErrorInfo]`". Same file line 469 says `ai_client.send(...)` returns "`Result[str, ErrorInfo]`".

**Reality:** `conductor/code_styleguides/error_handling.md:91` defines:
```python
class Result(Generic[T]):
    data: T
    errors: list[ErrorInfo] = field(default_factory=list)
```
The signature is `Result[T]` (generic over success type only). Errors is a FIELD, not a type parameter. Correct notation is `Result[str]` (where `.errors: list[ErrorInfo]` is always the shape).

**Fix:** Replace all `Result[str, ErrorInfo]` in `guide_ai_client.md` with `Result[str]` (and reference the field `.errors: list[ErrorInfo]` separately). Same fix in any other guide that uses this notation.

### C6 — `RAGChunk` schema is stale in `guide_rag.md` 🟠

**Claim:** `docs/guide_rag.md:343-350` documents `RAGChunk` fields as `text, source_path, start_line, end_line, embedding`.

**Reality:** `src/rag_engine.py:20-21` defines `RAGChunk` with an additional `id: str = ""` field, added per `cruft_elimination_20260627` Phase 5 ("Added `id: str` field to RAGChunk dataclass"). The guide does not show this field.

**Fix:** Update `guide_rag.md:343-350` to include the `id: str = ""` field. Also update `docs/guide_models.md` `RAGChunk` dataclass section to include `id`.

### C7 — Provider count: Readme.md says 5, guide says 8 🟠

**Claim 1:** `docs/Readme.md:34` says `guide_ai_client.md` covers "multi-provider LLM singleton (5 providers: Gemini, Anthropic, DeepSeek, MiniMax, Gemini CLI)".

**Claim 2:** `docs/guide_ai_client.md:9-10` says "The module is a unified LLM client for 8 providers. It abstracts the differences between providers (Gemini, Anthropic, DeepSeek, MiniMax, Gemini CLI, Qwen, Grok, Llama) ... The OpenAI-compatible vendors all call the shared helper in `src/openai_compatible.py`".

**Fix:** Update `docs/Readme.md:34` to say "8 providers" (matching the actual codebase).

### C8 — Test count: Readme.md says 322, guide says 251 🟠

**Claim 1:** `docs/Readme.md:31` says "322 test files". Same file line 365 says "`guide_testing.md # 322 test files`".

**Claim 2:** `docs/guide_testing.md:9` says "Manual Slop has **251 test files**". Same file line 26 says "test_*.py # 251 test files".

**Reality:** The codebase has 251 test files; the Readme is stale (the 322 number likely came from a time when `_sim.py` files were double-counted, or included the `_e2e.py` files).

**Fix:** Update `docs/Readme.md:31, 365` to "251 test files".

### C9 — Command count: Readme.md says 50+, guide says 33 🟠

**Claim 1:** `docs/Readme.md:30` says "Command Palette ... 50+ built-in commands".

**Claim 2:** `docs/guide_command_palette.md:196` says "The 33 commands currently shipped in `src/commands.py`". Same file line 4 says "33 registered commands".

**Fix:** Update `docs/Readme.md:30` to "33 built-in commands".

### C10 — `metadata_promotion_20260624` was supposed to add 12 dataclasses; 11 went to `type_aliases.py` + 1 to `rag_engine.py` 🟡

**Claim:** `conductor/chronology.md:4` (the canonical index): "add 12 per-aggregate `@dataclass(frozen=True)` classes (CommsLogEntry, HistoryMessage, FileItem, ToolDefinition, RAGChunk, SessionInsights, DiscussionSettings, CustomSlice, MMAUsageStats, ProviderPayload, UIPanelConfig, PathInfo)".

**Reality:** The 12 includes `RAGChunk`, but `RAGChunk` was actually placed in `src/rag_engine.py:20-21`, not in `src/type_aliases.py`. The other 11 went to `type_aliases.py` (some with `from_dict()`, some not). So the spec said "12 in type_aliases.py" but the implementation put 11 in `type_aliases.py` + 1 in `rag_engine.py`.

**Fix:** Update `conductor/chronology.md:4` to clarify the location split. Update `conductor/tracks/metadata_promotion_20260624/spec.md` G3 to reflect the actual implementation.

---

## Category 3: Status Drift in `tracks.md` and `chronology.md` 🟠

The "active queue" in `tracks.md` does not match what `chronology.md` says is shipped.

### C11 — `live_gui_test_fixes_20260618` shipped but `tracks.md` says "active" 🟠

**Claim:** `conductor/tracks.md` row 7d shows `live_gui_test_fixes_20260618` with status "**active**" (in the "Active Tracks (Current Queue)" table).

**Reality:** `conductor/chronology.md:12` says the track is "Completed" with `ff40138f..6ce55cba (2)` commits.

**Fix:** Move row 7d out of the Active Tracks table and into the appropriate Phase section (or mark as shipped with link to TRACK_COMPLETION).

### C12 — `test_sandbox_hardening_20260619` shipped but `tracks.md` says "ready to start" 🟠

**Claim:** `conductor/tracks.md` row 16 shows `test_sandbox_hardening_20260619` with status "**ready to start**".

**Reality:** `conductor/chronology.md:11` says "Completed" with `ec0716c9..eec44a09 (9)` commits. `TRACK_COMPLETION_test_sandbox_hardening_20260619.md` exists at the documented path. `tracks.md` row 16 also has `16 | A | Test Sandbox Hardening` listed in the active queue.

**Fix:** Mark as shipped; move to Phase section; link to `TRACK_COMPLETION_test_sandbox_hardening_20260619.md`.

### C13 — `metadata_promotion_20260624` listed as active but honest state is Phase 1 done + Phases 2-10 NO-OP 🟠

**Claim 1:** `conductor/tracks.md` (per my earlier read; full text was truncated) shows the track.

**Claim 2 (honest):** `conductor/chronology.md:4` says: "Tier 2 added the dataclasses (with drifted field types vs the plan), completed Phase 1 (Ticket migration), but classified Phases 2-10 as no-op per FR2. State on branch: lied about completion (`status = 'completed'` with all phases 'completed (no-op per audit)'). Tier 1 followup corrected to honest state (`status = 'active'`, `current_phase = 0`)."

**Contradiction:** The track is labeled "active at phase 0" but Phase 1 was completed and shipped. The "no-op" classification of Phases 2-10 means the rest of the work is "documented as deferred" not "to do". An agent reading the active queue would think this is a track to start; in reality it's a track where Phase 1 is done and the rest is filed as a no-op.

**Fix:** Move `metadata_promotion_20260624` to a "completed Phase 1; Phases 2-10 classified NO-OP" status. Either complete the parent track (the work is done) or rename the state to reflect "1/10 phases done; remaining deferred" so agents don't pick it up.

### C14 — `result_migration_20260616` parent and sub-track status drift 🟡

**Claim 1:** `conductor/tracks.md` row 6 (per my earlier read) shows `result_migration_20260616` as "active".

**Claim 2:** `conductor/chronology.md:6` shows `result_migration_baseline_cleanup_20260620` as "active". But `docs/reports/RESULT_MIGRATION_CAMPAIGN_STATUS_20260619.md` (updated by Phase 9 patch 2026-06-21) says the campaign is closed.

**Contradiction:** The 5-sub-track campaign (`result_migration_20260616` with sub-tracks 6d-1 through 6d-6) is 100% complete per the close-out report. But `tracks.md` and `chronology.md` still show "active".

**Fix:** Update the parent track state to "closed" or "completed" with link to the campaign close-out. Same for sub-track 6 (baseline_cleanup).

### C15 — `result_migration_baseline_cleanup_20260620` status in `tracks.md` 🟡

**Claim:** `conductor/chronology.md:6` shows `result_migration_baseline_cleanup_20260620` as "active". Per `TRACK_COMPLETION_result_migration_cruft_removal_20260620.md`, the campaign closed 2026-06-20 with Phase 9 patch 2026-06-21.

**Fix:** Mark as shipped/closed.

---

## Category 4: Internal Styleguide Contradictions 🟠🟡

### C16 — `python.md` §10 Anti-OOP rule vs actual codebase 🟠

**Claim:** `conductor/code_styleguides/python.md:73-110` says "Anti-OOP Conventions" + "Hard Rules (Enforced by lint)" — "Never write a class for a single method. Use a function." "Never use inheritance for code reuse. Compose with standalone functions." "Never use private methods (`_method`). Module-level functions with clear names suffice." "No nested classes. Define helper types at module level." "No decorator classes."

**Justification rule (`python.md:87-101`):** "A class is justified ONLY when ALL of: 1. It holds mutable state that must be encapsulated. 2. It has 3+ related methods that share state. 3. It implements a behavioral interface used polymorphically (not just data grouping)."

**Self-contradiction (`python.md:203-205`):** "**Removed anti-pattern (2026-06-11):** the prior version of this section said 'extremely large files that violate the Anti-OOP rule by necessity.' ... The `App` class in `src/gui_2.py` is not 'violating' anything by being large; it's the natural shape of a class that owns the GUI orchestration."

**Reality:** The codebase has `App` (150+ methods), `AppController` (166KB), `ConductorEngine`, `WorkerPool`, `RAGEngine`, `MultiAgentConductor`, etc. — all stateful classes. App does NOT satisfy criterion #3 (used polymorphically — it's a singleton). So App and AppController would fail the §10.4 rule.

**Contradiction within the SAME FILE:** §10.1-§10.3 (strict bans) + §10.4 (3 criteria) + §203 (admission that the rule doesn't apply to App).

**Fix:** Rewrite §10 to clarify:
- §10.1: "Module-level functions for stateless logic (default)."
- §10.2: "Classes are justified for stateful subsystems (App, AppController, ConductorEngine, RAGEngine, etc.). The 3 criteria are: holds state + 3+ methods sharing state + used as a singleton OR has a behavioral interface." — drop criterion #3 OR reword as "or is instantiated as a stateful subsystem singleton."
- §10.5 (new): "Examples of justified classes in this codebase: `App` (150+ methods, 90 delegation targets, holds the GUI state), `AppController` (the headless state container), `ConductorEngine` (orchestration state machine), `WorkerPool` (thread/semaphore state)."

### C17 — `type_aliases.md` line 19 table contradicts its own body 🟠

**Claim (line 19):** "`Metadata` | `dict[str, Any]` | The root alias; any key-value record"

**Claim (line 42):** "**UPDATED 2026-06-25 (the C11/Odin/Jai-in-Python mandate).** `Metadata` is the typed fat struct at the wire boundary. It is `@dataclass(frozen=True, slots=True)` with explicit fields..."

**Contradiction within the SAME FILE:** The table at line 19 says `Metadata` is `dict[str, Any]`. The body at line 42 says it's a typed dataclass. The table was NOT updated when the body was rewritten.

**Claim (line 73):** "The underlying type is still `dict[str, Any]`; the alias name is the documentation."

**Claim (line 81):** "**When NOT to promote:** ... they keep `Metadata: TypeAlias = dict[str, Any]` as the catch-all."

**Claim (line 59-61):** "`Metadata` is **NOT** `TypeAlias = dict[str, Any]`. It is a typed fat struct. ... **Anti-pattern (banned):** `Metadata: TypeAlias = dict[str, Any]` (the lazy-typing escape hatch)."

**Internal contradiction:** Lines 19, 73, 81 say `Metadata` IS `dict[str, Any]`. Lines 42, 59-61 say it IS NOT. Lines 73 says "underlying type is still dict[str, Any]" — which means the aliases (`CommsLogEntry = Metadata` etc.) are all still dicts. But line 75-77 introduces per-aggregate dataclasses which contradict this.

**Fix:** Rewrite the table at line 13-34 to reflect post-2026-06-25 reality:
- Line 19 table: `Metadata` | `@dataclass(frozen=True, slots=True)` (36 fields) | The boundary type at TOML/JSON wire
- Line 24 table: `FileItem` | `@dataclass(frozen=True)` | A single file in the context
- Etc. — each per-aggregate alias should now point to its own dataclass, not to `Metadata`
- Line 73: REMOVE the "underlying type is still dict[str, Any]" claim
- Line 81: REMOVE the "keep `Metadata: TypeAlias = dict[str, Any]` as the catch-all" — `Metadata` IS a dataclass now

### C18 — `python.md` says banned but doesn't have lint enforcement for 3 of 7 banned patterns 🟡

**Claim:** `conductor/code_styleguides/python.md:402-413` says:
- Line 403: `scripts/audit_weak_types.py --strict` — flags `dict[str, Any]`, `Any`, anonymous tuple returns ✅ EXISTS
- Line 407: `scripts/audit_optional_in_3_files.py --strict` — flags `Optional[T]` in the 3 refactored files ✅ EXISTS (but named wrong, see C1)
- The boundary-layer audit — planned in `conductor/tracks/cruft_elimination_20260627/spec.md` ❌ NOT BUILT
- Line 413: `scripts/audit_imports.py (planned)` — flags local imports outside `try/except ImportError` blocks ❌ NOT BUILT

**Reality:** 7 banned patterns, only 2 have audit scripts. The boundary-layer audit and audit_imports are "planned" not "implemented".

**Fix:** Either build the missing audits OR explicitly mark them as "to-be-implemented, currently unenforced" so agents know what to actually check.

---

## Category 5: Result Migration Campaign Docs 🟡

### C19 — The 9 legacy `Result[T]` wrapper obliteration is documented but not in styleguide 🟡

**Claim:** `conductor/tracks/result_migration_cruft_removal_20260620/spec.md` documents the "OBLITERATE principle: no pass-throughs; no backward compat; in-site callers rewritten to use `_x_result(...).ok` directly; the dead code dies." This is a specific pattern that's enforced in the cleanup but isn't in `conductor/code_styleguides/`.

**Fix:** Add a "Result migration anti-patterns" section to `error_handling.md` documenting the OBLITERATE principle (when a function is migrated to Result, the legacy wrapper should be deleted; callers must be migrated in the same commit).

---

## Category 6: `cruft_elimination_20260627` state docs 🟡

### C20 — Phase 7 ("60 Any params + 11 dict[str, Any]") numbers don't match `audit_weak_types.py` baseline 🟡

**Claim 1 (spec):** `conductor/tracks/cruft_elimination_20260627/spec.md` G4 says "Zero `Any` parameter types in internal code. Same grep with `: Any` returns 0" — target is 60 sites removed.

**Claim 2 (audit baseline):** Per `boundary_layer_20260628.md` and the audit baseline, there are 60 `Any` params + 11 `dict[str, Any]` params in the migration-target 14 files (post-refactor). The `audit_weak_types.baseline.json` records the post-refactor count.

**Reality:** The `audit_weak_types.py --strict` checks against the baseline JSON. The baseline count must be the same as the spec's target. If the spec says "60 Any sites" but the audit baseline is higher, the spec is wrong. If the baseline is the same, the spec is consistent.

**Fix:** Reconcile `cruft_elimination_20260627/spec.md` G3 + G4 + `audit_weak_types.baseline.json` numbers. Add a line "Baseline at start of Phase 7: 60 Any + 11 dict[str, Any]" with the exact JSON reference.

---

## Category 7: Naming and Misc 🟢

### C21 — `audit_optional_in_3_files.py` checks 4 files 🟢

**Claim:** Filename says "3 files". `BASELINE_FILES` defines 4 files (mcp_client, ai_client, rag_engine, code_path_audit).

**Fix:** Rename to `audit_optional_in_baseline_files.py` (see C1).

---

## Summary Table

| # | Contradiction | Severity | Affected Files |
|---|---|---|---|
| C1 | `audit_optional_in_3_files.py` covers 4 files | 🟠 | `python.md`, `error_handling.md`, `docs/AGENTS.md` |
| C2 | Optional[T] ban scope ambiguity | 🟠 | `error_handling.md`, `docs/AGENTS.md` |
| C3 | `audit_imports.py` "planned" but never built | 🟠 | `python.md` |
| C4 | Pre-commit hooks only in Tier 2 sandbox | 🟡 | `docs/AGENTS.md` |
| C5 | `Result[str, ErrorInfo]` notation wrong | 🟠 | `guide_ai_client.md` |
| C6 | `RAGChunk` schema missing `id: str` field | 🟠 | `guide_rag.md`, `guide_models.md` |
| C7 | Provider count: Readme 5 vs guide 8 | 🟠 | `docs/Readme.md` |
| C8 | Test count: Readme 322 vs guide 251 | 🟠 | `docs/Readme.md` |
| C9 | Command count: Readme 50+ vs guide 33 | 🟠 | `docs/Readme.md` |
| C10 | 12 dataclasses location split | 🟡 | `chronology.md`, `metadata_promotion_20260624/spec.md` |
| C11 | `live_gui_test_fixes_20260618` "active" but shipped | 🟠 | `tracks.md` |
| C12 | `test_sandbox_hardening_20260619` "ready to start" but shipped | 🟠 | `tracks.md` |
| C13 | `metadata_promotion_20260624` status confusion | 🟠 | `tracks.md`, `chronology.md` |
| C14 | `result_migration_20260616` parent stale | 🟡 | `tracks.md` |
| C15 | `result_migration_baseline_cleanup_20260620` stale | 🟡 | `tracks.md`, `chronology.md` |
| C16 | `python.md` §10 Anti-OOP vs App+AppController | 🟠 | `python.md` |
| C17 | `type_aliases.md` line 19 table vs body | 🟠 | `type_aliases.md` |
| C18 | 2/7 banned patterns have audit scripts | 🟡 | `python.md` |
| C19 | OBLITERATE principle not in styleguide | 🟡 | `error_handling.md` |
| C20 | cruft_elimination Phase 7 numbers vs baseline | 🟡 | `cruft_elimination_20260627/spec.md` |
| C21 | `audit_optional_in_3_files.py` checks 4 | 🟢 | script filename |

---

## Recommended Fix Priority

### Tier 1 — Fix now (broken conventions)
1. **C1+C21** — Rename `audit_optional_in_3_files.py` → `audit_optional_in_baseline_files.py` and decide whether to extend coverage to all `src/*.py` or document the 4-file scope honestly.
2. **C2** — Decide whether the ban is enforceable globally; if yes, build the extension; if no, update `docs/AGENTS.md` to honestly say "enforced on 4 baseline files; see cruft_elimination_20260627 for the rest".
3. **C3+C18** — Either build `scripts/audit_imports.py` and the boundary-layer audit, or explicitly mark them as to-be-implemented.
4. **C5** — Replace `Result[str, ErrorInfo]` → `Result[str]` everywhere in `guide_ai_client.md`.
5. **C16+C17** — Rewrite the contradictory sections of `python.md` §10 and `type_aliases.md` line 19 to reflect post-2026-06-25 reality.

### Tier 2 — Fix in next docs sync track
6. **C6** — Update `RAGChunk` schema in guides.
7. **C7+C8+C9** — Update counts in `docs/Readme.md`.
8. **C11+C12+C13+C14+C15** — Reconcile `tracks.md` and `chronology.md` against actual shipped state.
9. **C10** — Clarify dataclass location split in `metadata_promotion_20260624` spec.

### Tier 3 — Followup track (not blocking)
10. **C4** — Decide whether main-repo pre-commit enforcement is needed.
11. **C19** — Add OBLITERATE principle to `error_handling.md`.
12. **C20** — Reconcile baseline numbers.