Phase 5 (1 of 9 cruft sites obliterated):
OBLITERATED: RAGEngine._chunk_code wrapper. It delegated to _chunk_code_result
and provided a fallback to _chunk_text on AST failure.
Migration: index_file() now calls _chunk_code_result directly with .ok check
+ chunk-size threshold check + fallback to _chunk_text inline. The structured
ErrorInfo is propagated if needed (no caller currently consumes it).
Sub-track 5 tests updated:
- tests/tier2/phase13_invariant_test.py: _chunk_code moved to obliterated list
- tests/tier2/phase13_site2_test.py: _legacy_no_broad_except -> _legacy_obliterated
- tests/test_cruft_removal.py: 2 new tests (wrapper-obliterated invariant +
caller-uses-result invariant)
PITFALL encountered: the edit_file tool removed a leading space on the
next class method's 'def' line, causing an IndentationError. Fixed by
binary-write replacement preserving CRLF + leading-space styleguide convention
(project uses 1-space indentation; class body methods start at column 1).
Test result: 124/124 pass.
Audit gate: src/rag_engine.py --strict exits 0 (no new violations).
Wrapper count: 3 -> 2 (Phase 6 remaining: gui_2 2).
Phase 3 (1 of 9 cruft sites obliterated):
The legacy wrapper _resolve_and_check(raw_path) returned tuple[Path|None, str],
dropping the structured ErrorInfo from _resolve_and_check_result. Callers in
dispatch_tool_call (py_remove_def, py_add_def, py_move_def, py_region_wrap) used
the pattern 'p, err = _resolve_and_check(path); if err: return err' which is
exactly the false drain the user wants obliterated.
Migration:
- DELETED: _resolve_and_check wrapper (lines 175-188 in src/mcp_client.py)
- UPDATED: 5 callers in dispatch_tool_call now call _resolve_and_check_result
directly with .ok check + NilPath check + structured error routing
- UPDATED: 4 test files that monkey-patched _resolve_and_check to mock the
Result helper instead:
- test_mcp_ts_integration.py (1 mock)
- test_ts_c_tools.py (2 mocks)
- test_ts_cpp_tools.py (8 mocks)
- test_cruft_removal.py (NEW; 4 tests including the wrapper-obliterated
invariant + the audit-script-finds-zero invariant + 2 dispatch tests)
Test result: 51/51 pass (31 baseline + 16 heuristic + 4 cruft).
Audit gate: src/mcp_client.py --strict exits 0 (no new violations introduced).
Baseline audit: --include-baseline --strict exits 1 only due to 4 pre-existing
non-baseline INTERNAL_RETHROW sites in outline_tool.py / warmup.py /
vendor_capabilities.py (out of scope per spec).
The wrapper IS DELETED. No pass-through. No backward compat. The dead code dies.
Phase 2 done:
- Task 2.0: styleguide re-read (ack committed)
- Task 2.1: audit script written + revised (excludes the proper
_result helpers themselves from the wrapper pattern)
- Task 2.2: 9 wrappers found (all P1; no P3 confirmed)
- Task 2.3: PHASE2_WRAPPER_AUDIT.md committed (per-wrapper mapping)
- Task 2.4: Phase 2 invariant test pending (will be added as part
of Phase 3 work)
Deviation from spec: spec claimed 8+ wrappers; actual count is 9.
Spec also claimed P3 pattern ('returns Result unchanged') was found;
actual scan found 0 P3 patterns. The earlier 111 was a false positive
inflated by an audit bug that flagged the _result helpers themselves
(their bodies do call other _result helpers legitimately).
Next: Phase 3 (mcp_client: _resolve_and_check). 1 wrapper, 7 callers.
Re-read for Phase 2:
- 'What is NOT a drain point' (the 5 anti-drains)
- sys.stderr.write alone
- logging.error / logger.exception alone
- return default_value
- pass (silent)
- traceback.print_exc alone
- 'Boundary types vs. drain points' (the two concepts are complementary)
- 'The Broad-Except Distinction' table (each catch site classified by
what it does with the exception)
- 'Heuristic D' (the 5 drain point patterns: HTTP response, GUI popup,
sys.exit, telemetry, bounded retry)
Key principle applied to Phase 2 inventory: a wrapper that does
def _x(): return _x_result(...).data is equivalent to 'return
default_value' — the structured ErrorInfo is lost. The migration is
to have callers use _x_result(...).ok and route the error to a
documented drain (which may be re-raising, telemetry, or a caller-
specific fallback).
Phase 2 inventory results (vs spec claim of 8+ confirmed):
- Total wrappers: 9 (all P1 drop-errors-via-.data; no P3 confirmed)
- By file: mcp_client 1, ai_client 5, rag_engine 1, gui_2 2
Audit script revision:
The spec's audit logic incorrectly flagged the proper _result helpers
as wrappers (they contain _result( calls in their body when they call
OTHER _result helpers). The fix: require the function name NOT to end
in _result, AND the body must call (name + _result) specifically. This
narrowed the finding from 111 (false-positive) to 9 (true legacy wrappers).
Public MCP tool wrappers (search_files, list_directory, etc.) are NOT
flagged: they ARE the protocol drain points, returning str per JSON-RPC
wire format.
Phase 1 done:
- Task 1.1: PHASE1_AUDIT_BASELINE.json synthesized from the 3 per-file
inventory docs (NOT live re-audit; live re-audit would produce the
post-migration state which is not the baseline)
- Task 1.2: N/A (inventory docs were already split per sub-track 5)
- Task 1.3: 31/31 baseline + 16/16 heuristic = 47/47 PASS
Deviation: spec claimed 7 failing tests; actually 5 failed. The 2 extra
were the 'inventory_docs_exist' tests which already passed because the
inventory docs (PHASE1_INVENTORY_*.md) were committed before this
track started. The 5 failures were all PHASE1_AUDIT_BASELINE.json
lookups that pointed to a regenerated-as-current-state file.
Next: Phase 2 (final wrapper inventory audit).
Phase 1 deviation from spec: the original PHASE1_AUDIT_BASELINE.json
was gitignored (tests/artifacts/ is in .gitignore) and lost when the
working tree rebuilt. Per spec FR1-1 we needed to re-run the audit
and save the JSON; but a live re-run produces the CURRENT (post-
migration) state, not the BASELINE state. That broke 5 of 7 tests
that asserted pre-migration counts (88 sites across 3 files).
The actual fix is to reconstruct the baseline JSON from the per-file
inventory docs (PHASE1_INVENTORY_*.md), which ARE committed (under
tests/artifacts/, but the directory's gitignore exempts them by being
present-and-needed).
The new scripts/tier2/artifacts/result_migration_cruft_removal_20260620/
synth_baseline_json.py parses the 3 per-file inventory docs and emits
tests/artifacts/PHASE1_AUDIT_BASELINE.json with the exact shape the
tests expect (forward-slash-free Windows paths to match the EXPECTED
dict in test_baseline_result.py).
Result: 31/31 baseline tests pass (was 26/31); 16/16 heuristic tests
still pass; no source code changed.
Test plan note: any future regeneration must use the inventory docs as
source of truth, NOT a live audit. The audit is a moving target once
migration begins.
Acknowledges Rule #0 of the AI Agent Checklist (lines 809-940 of the
styleguide). Sections re-read for this track:
- 5 Patterns (Nil-Sentinel, Zero-Init, Fail-Early, AND over OR, Error
Info as Side-Channel)
- Drain Points (5 patterns + 5 'NOT a drain point' anti-patterns)
- Boundary Types (third-party SDK, stdlib I/O, FastAPI)
- Broad-Except Distinction (the table classifying every catch site
by what it does with the exception)
- AI Agent Checklist (5 MUST-DO + 7 MUST-NOT-DO + 3 boundary patterns)
Key principle applied to this track: 'error dropping is NOT a drain'
(the legacy wrapper def _x(): return _x_result(...).data defeats
the entire purpose of the Result[T] migration; the wrapper silently
swallows the error from _x_result).
Phase 0 task 0.1: register the new track in the Active Tracks table.
The campaign-close-out track is added as row 6d-6 (after sub-track 5 which
shipped 2026-06-20). The dependency links to sub-track 5 (which is the
data-plane source: 91 _result helpers, but the legacy wrappers that
defeat error propagation are still in place).
Per user directive 2026-06-20: OBLITERATE every legacy wrapper; no
pass-throughs; no backward compat.
Final cleanup track of the 5-sub-track result-migration campaign.
Obliterates every legacy wrapper in src/ — the false-drain pattern
introduced in sub-track 3 Phase 6 Group 6.3 (def _x(): return _x_result(...).data)
which silently swallows the Result errors and defeats the entire purpose
of the Result[T] migration.
Per user directive (2026-06-20): 'I want to obliterate excess code. I'm
trying to prune the codebase of bad programming practices. I can't have
false drain sites just to support a legacy connection when the on-site
call can just be properly rewritten to use the proper path.'
Scope:
- 8+ legacy wrappers in src/ (preliminary; Phase 2 will enumerate exactly)
- 91 _result helpers total (many of which are only called via the legacy
wrapper, meaning errors are silently dropped at every call site)
- 7 failing inventory tests in tests/test_baseline_result.py from sub-track 5
(PHASE1_AUDIT_BASELINE.json was never committed; 3 per-file inventory
docs were collapsed to 1 combined doc; tests reference the 3-file convention)
The 9-Phase Structure:
0. Setup + styleguide re-read
1. Fix the 7 failing tests (test scaffolding repair; no production code)
2. Final detailed audit (full legacy wrapper inventory in
tests/artifacts/PHASE2_WRAPPER_AUDIT.md)
3-7. Per-file wrapper removal (mcp_client, ai_client, rag_engine, then
other src/ files per Phase 2 inventory)
8. Audit gate + end-of-track report + campaign close-out
The migration pattern per wrapper:
BEFORE (legacy wrapper — false drain):
def _x_result(...): -> Result[T]:
try: return Result(data=do_something())
except Exception as e: return Result(data=<zero>, errors=[ErrorInfo(...)])
def _x(...): # ← false drain
result = _x_result(...)
if not result.ok: pass # ERROR DROPPED
return result.data
AFTER (legacy wrapper DELETED; caller rewritten):
def _x_result(...): -> Result[T]: # unchanged
...
# caller is rewritten:
def caller(...):
result = _x_result(...)
if not result.ok:
log_error_to_drain(result.errors[0])
return <caller-specific-fallback>
return result.data
# def _x(...): ← DELETED (no pass-through; no backward compat)
No pass-throughs. No backward compat. The dead code dies.
Per-wrapper atomic commit (1 wrapper = 1 commit).
Files:
- spec.md (Section 0-11; 4 FRs for Phase 1; per-phase migration strategy;
explicit 'no pass-throughs' principle)
- plan.md (anti-sliming protocol; file structure; per-phase task list)
- metadata.json (12 VCs; 3 risks; 1 pre-existing failure (7 failing tests))
- state.toml (9 phases; ~50 tasks; 15 verification entries;
campaign_closeout = true)
Total: 4 files, ~1300 lines added. Closes the result-migration campaign
when SHIPPED (0 legacy wrappers + 0 test failures + 0 audit violations
across all 65 src/ files).
Next: Tier 2 picks up Phase 0 (setup + styleguide re-read) per the
task list in state.toml. The 7 failing tests are fixed in Phase 1.
The full legacy wrapper enumeration is Phase 2. Wrapper removal begins
Phase 3 (mcp_client).
Bug: Phase 11 sites 5+6 migration extracted _set_tool_preset_result and
_set_bias_profile_result helpers. The _set_tool_preset_result helper
modifies _active_tool_preset, _tool_approval_modes, _agent_tools without
declaring them as global, which causes the assignments to create LOCAL
variables instead of modifying the module-level globals.
This regression broke tests/test_bias_integration.py::test_set_tool_preset_with_objects:
preset = ToolPreset(name='ObjTest', categories={'General': [Tool(name='read_file', approval='auto')]})
with patch('src.tool_presets.ToolPresetManager.load_all', return_value={'ObjTest': preset}):
ai_client.set_tool_preset('ObjTest')
assert ai_client._agent_tools['read_file'] is True
# Fails: KeyError 'read_file' (the helper created a local _agent_tools,
# not modifying the module global; set_tool_preset legacy then ran
# cache-invalidation but never assigned _agent_tools to the test's view)
Fix: Add 'global _active_tool_preset, _tool_approval_modes, _agent_tools'
declaration to _set_tool_preset_result. The original set_tool_preset had
this declaration at the top; the helper extraction lost it.
Audit: no audit change (the helper still classifies as BOUNDARY_CONVERSION
via Heuristic A 'returns Result' pattern).
Site 5 (BC at L290): _async_search_mcp (nested in _search_mcp) had:
try:
data = json.loads(res_str)
if isinstance(data, list): return data
elif isinstance(data, dict) and 'results' in data: return data['results']
return []
except:
return []
Body: bare 'except:' + return [] = empty default = SS-style violation.
Migrated to Result[T] via new module-level helper _parse_search_response_result:
- Returns Result(data=parsed_list) on success
- Returns Result(data=None, errors=[ErrorInfo]) on JSON parse failure
- Handles the list/dict/no-results branch logic
The helper is module-level (does not use self) and is placed BEFORE
class RAGEngine to avoid breaking the class definition (a def at column 0
inside a class ends the class prematurely).
Legacy _async_search_mcp delegates to the helper; on Result errors,
returns [] (preserving the original behavior).
Audit: rag_engine BC 1 -> 0; migration-target: 0.
Remaining 4 INTERNAL_RETHROW sites are Pattern 1/3 of the styleguide
(known audit limitation).
index_file had 3 try/except sites with similar patterns:
Site 3 (BC at L247): try: mtime = os.path.getmtime(full_path); except Exception: return
Site 4 (BC at L261): try: with open(full_path, ...) as f: content = f.read(); except Exception: return
Site 6 (SS at L255): try: res = self.collection.get(...); ...; except Exception: pass
Body: broad catch + early return/pass = SS-style violation.
New helpers:
- _get_file_mtime_result(full_path) -> Result[float]
Catches OSError only (specific to file stat failures).
- _check_existing_index_result(file_path, mtime) -> Result[bool]
Catches broad Exception (chromadb collection.get failures vary).
Returns data=True if already indexed (skip), data=False if needs re-indexing.
- _read_file_content_result(full_path) -> Result[str]
Catches (OSError, UnicodeDecodeError) (file I/O + encoding failures).
Legacy index_file calls each helper; on Result errors, returns early
(preserving the original behavior of skipping the file on failure).
Audit: rag_engine BC 3 -> 1 (L341 _async_search_mcp remaining).
SS: 1 -> 0.
ed