Phase 7 of code_path_audit_phase_3_provider_state_20260624.
Per-provider history is now accessed via provider_state.get_history()
at call sites; the 12 module-level _X_history/_X_history_lock aliases
are no longer referenced anywhere in production code (helper function
DEFINITIONS that take history as a parameter are unaffected).
TIER-2 READ conductor/code_styleguides/error_handling.md before Phase 2 (deepseek migration; RLock re-entrance critical).
Phase 2 of code_path_audit_phase_3_provider_state_20260624. 11 sites in _send_deepseek (lines 2186-2414) migrated from _deepseek_history/_deepseek_history_lock to local capture history = provider_state.get_history('deepseek'). The RLock re-entrance is critical here — this was the deadlock-prone site that prompted cc7993e5. The local capture pattern uses one acquisition per function instead of one per call site, minimizing lock acquisitions while preserving the same RLock instance that _deepseek_history_lock aliased to.
4 with-blocks migrated (lines 2195, 2215, 2347, 2412). 6 _deepseek_history alias references migrated to history (lines 2196, 2197, 2201, 2216, 2354, 2414).
Verified: 30 tests pass across test_provider_state_migration (14) + test_deepseek_provider (7) + 5 ai_client test files. The test_lock_acquisition_no_deadlock regression test verifies RLock re-entrance works correctly inside the with history.lock: blocks.
Conventions: 1-space indentation, CRLF preserved, no comments added.
TIER-2 READ conductor/code_styleguides/error_handling.md before Phase 1 (anthropic migration).
Phase 1 of code_path_audit_phase_3_provider_state_20260624. 13 call sites in _send_anthropic (lines 1430-1575) migrated from the module-level _anthropic_history alias to a local capture history = provider_state.get_history('anthropic'). The local capture pattern is used (instead of repeated provider_state.get_history() calls) to minimize lock acquisitions and improve readability.
The migration preserves behavior: ProviderHistory is the same singleton that _anthropic_history aliased to, so the migration is a pure refactor. The lock acquisition pattern is unchanged (this function does not acquire _anthropic_history_lock; thread-safety comes from _send_anthropic being called per-thread).
Verified: 37 tests pass across test_provider_state_migration.py + 6 ai_client test files.
Conventions: 1-space indentation, CRLF preserved, no comments added.
TIER-3 READ AGENTS.md + conductor/workflow.md + conductor/code_styleguides/error_handling.md + the 4 source files + 3 test files before this commit.
The code_path_audit_phase_2_20260624 track (Tier 2) shipped 11 audit
fixes (4 NG1 + 7 NG2) but used a heuristic bypass for 4 of the NG2
wrappers: legacy T | None functions that exist only to maintain test
patcher compatibility. Per the review at
docs/reports/REVIEW_TIER2_code_path_audit_phase_2_20260624.md Finding 8,
this track eliminates the legacy wrappers properly.
11 wrappers eliminated (8 main + 3 _legacy_compat inner):
- src/ai_client.py: get_current_tier (1 src + 1 test consumer)
- src/ai_client.py: _gemini_tool_declaration + _legacy_compat (2 test consumers)
- src/ai_client.py: run_tier4_patch_callback + _legacy_compat (was 0 direct callers
but had 2 callback references in app_controller/multi_agent_conductor;
callback contract migrated to Callable[[str, str], Result[str]] instead of
preserving an Optional[str] adapter)
- src/mcp_client.py: _get_symbol_node + _legacy_compat (8 in-file consumers)
- src/mcp_client.py: find_in_scope (nested inside _get_symbol_node_result;
private impl detail, audit doesn't catch T | None, left as-is)
- src/external_editor.py: launch_diff (1 src + 3 test + 1 live_gui test consumer)
- src/external_editor.py: launch_editor (no consumers; deleted)
- src/session_logger.py: log_tool_output (2 src + 3 test consumers)
- src/project_manager.py: parse_ts (no consumers; deleted)
For each consumer: replace legacy_fn(args) with legacy_fn_result(args).data.
For T | None checks: replace if x is None: with if not result.ok: or
if not result.ok or not isinstance(result.data, ...) (depending on pattern).
For run_tier4_patch_callback specifically: the wrapper was a callback adapter
(not a backward-compat shim) and had 2 callback references as consumers.
Rather than keep the adapter (which would re-introduce the Optional[str]
return that the strict audit catches), the patch_callback contract was migrated
from Callable[[str, str], Optional[str]] to Callable[[str, str], Result[str]]
in shell_runner.py + app_controller.py + 9 _send_<vendor>_result signatures
in ai_client.py. This propagates the Result[str] through the callback and
lets shell_runner unwrap with if r.ok and r.data instead of if patch_text.
Verification:
- audit_optional_in_3_files --strict: 0 return-type Optional[T] (down from 1)
- audit_exception_handling --strict: 0 violations (unchanged)
- audit_legacy_wrappers: 0 legacy wrappers (unchanged)
- 15 affected test files: 168 tests pass
- 8 mcp_client/structural/baseline test files: 55 tests pass
- 3 session/gui test files: 7 tests pass
- 0 return-type Optional[T] in src/ai_client.py (was 1: run_tier4_patch_callback)
Defense-in-depth check for the 2026-06-24 MCP regression: verifies that
the 2 MCP-config files (opencode.json + mcp_paths.toml) are present on
a tier-2 branch. If either is missing, the audit fails (exit 1) with
a clear diagnostic and the exact commands to restore the files.
The pre-commit hook (conductor/tier2/githooks/pre-commit, hardened in
eae75877) auto-unstages these files on commit, but does not prevent
the deletion from being in the commit's diff. The 2026-06-24 MCP
regression was exactly this: commit 6956676f deleted both files,
and the empty fix commit (2b7e2de1) was a no-op.
This audit catches that pattern 1 step earlier than the user noticing:
on push, on pre-merge, on manual review. It checks the branch's index
via 'git cat-file -e ref:file' (not the working tree) so it works in
CI without a checked-out working tree.
Usage:
# Audit the current HEAD
uv run python scripts/audit_branch_required_files.py
# Audit a specific ref
uv run python scripts/audit_branch_required_files.py --ref origin/tier2/foo
# JSON output for CI integration
uv run python scripts/audit_branch_required_files.py --json
The script's REQUIRED_FILES list has 2 entries (the actual MCP
regression targets), not 4. The 2 .opencode/agents/... files in
conductor/tier2/githooks/forbidden-files.txt are tier-2 sandbox-only
working tree files that are NEVER tracked in any branch (per commit
fab2e55b 'undo sandbox file leaks'); they live only in the tier-2
clone's working tree, copied there by setup_tier2_clone.ps1.
Exit codes:
0 - all required files present
1 - one or more required files missing (CI gate failure)
2 - usage error
Verified:
- HEAD: OK (files restored by user commits 71b51674 + cb1b0c1c)
- master: OK (files exist on master)
- 6956676f: FAIL (correctly detects the MCP regression commit)
- --json output is valid JSON
- --help shows clean usage
CI integration (when the project gets CI):
Add to .github/workflows/ci.yml (or equivalent):
- name: Verify tier-2 required files
run: uv run python scripts/audit_branch_required_files.py --strict
Or as a per-PR check on tier-2 branches:
- name: Verify required files on tier-2 PR
if: startsWith(github.head_ref, 'tier2/')
run: uv run python scripts/audit_branch_required_files.py --strict
The 7 code_path_audit*.py files (2604 lines total) are pure static
analysis tools. They do AST traversal of src/, no intrusive profiling,
no runtime markers. They were inlaid with src/ but only import:
- src.result_types (the Result[T] convention type)
- each other (the 6 siblings)
After the move:
- src/ is now pure application code; line-count audit metrics are clean
- scripts/code_path_audit/ is a new namespace-isolated subdir per
AGENTS.md 'scripts are namespace-isolated by directory' rule
TIER-3 READ AGENTS.md + conductor/workflow.md + conductor/edit_workflow.md
+ conductor/code_styleguides/code_path_audit.md + the 7 files before
this commit.
Changes:
- 7 files moved: src/code_path_audit*.py -> scripts/code_path_audit/
- 7 files updated: internal imports rom src.code_path_audit_X ->
rom code_path_audit_X (siblings in same subdir)
- 7 files updated: add sys.path.insert(0, str(Path(__file__).resolve().parents[2] / 'src'))
to find src.result_types when run standalone
- 5 test files updated: rom src.code_path_audit -> rom code_path_audit
+ sys.path setup to find the new subdir
- 6 throwaway scripts in scripts/tier2/artifacts/ updated: import path
+ sys.path setup (parents[3] / 'src' + parents[3] / 'scripts' / 'code_path_audit')
- 2 styleguide/spec references updated: conductor/code_styleguides/code_path_audit.md
+ conductor/tracks/code_path_audit_20260607/spec_v2.md
- 1 meta-audit docstring updated: scripts/audit_code_path_audit_coverage.py
- 1 type registry entry deleted: docs/type_registry/src_code_path_audit.md
(the type is no longer in src/)
- 1 type registry index updated: docs/type_registry/index.md (22 files, was 23)
Verification:
- 7/7 audit gates pass --strict (weak_types 102<=112, type_registry 22 files,
main_thread_imports OK, no_models_config_io OK, code_path_audit_coverage 0
violations, exception_handling 0 violations, optional_in_3_files 0 violations)
- 6/6 test files pass: test_code_path_audit, test_code_path_audit_integration,
test_code_path_audit_phase78, test_code_path_audit_phase89,
test_code_path_audit_ssdl_behavioral, test_metadata_nil_sentinel
- src/ line count: 29997 lines (down from 32621 = -2624 lines)
- scripts/code_path_audit/ line count: 2620 lines
ProviderHistory.lock changed from threading.Lock to threading.RLock in cc7993e5 to fix the re-entrant deadlock. Auto-regenerate the type registry to reflect the new field type and line number (after the duplicate @dataclass was removed).
3 Result helper methods (_deserialize_active_track_result, _serialize_tool_calls_result, _parse_token_history_first_ts_result) were nested inside cb_load_prior_log as inner defs. The inner 'return' at the except block (line 2370) made the rest of the function body (lines 2377-2392) unreachable past the nested defs' scope.
User fix: moved the 3 helpers to class level so they're reachable from other class methods (_refresh_from_project, _load_beads, etc.). Kept _resolve_log_ref and _read_ref_file_result as nested defs inside cb_load_prior_log because they're only used there.
File: -69 lines (the 60-line def cb_load_prior_log block from its original position), +64 lines (the 3 helpers + cb_load_prior_log re-added in the correct order).
Verified: ast.parse OK; from src import app_controller OK; AppController.cb_load_prior_log is reachable.
TIER-3 READ AGENTS.md + conductor/code_styleguides/error_handling.md + src/provider_state.py + src/ai_client.py:2148-2220 before provider-state-rlock-fix.
Tier 2's 25a22057 commit re-bound the 14 module globals in src/ai_client.py as
aliases to provider_state.get_history(...) instances. The ProviderHistory dunder
methods (__bool__, __len__, __iter__, __getitem__) all use \with self.lock:\.
The dunders are non-reentrant: \ hreading.Lock\ blocks if the lock is already
held. The call site in src/ai_client.py:2210-2217 acquires the lock via
\with _deepseek_history_lock:\ (alias to ProviderHistory.lock), then calls
_rerepair_deepseek_history(_deepseek_history) which does \history[-1]\
(acquires the lock again -> DEADLOCK). This caused
tests/test_deepseek_provider.py::test_deepseek_completion_logic to hang
with a 30s timeout.
Fix: change \ hreading.Lock\ to \ hreading.RLock\ in ProviderHistory.
The dunders can now be safely called while the lock is already held.
Also removed:
- Duplicate @dataclass decorator on ProviderHistory (line 25-26)
- Duplicate _PROVIDER_HISTORIES dict declaration (lines 64-71 and 74-81)
Acceptance: test_deepseek_provider (7/7) + test_provider_state + test_ai_client_result + test_ai_client_tool_loop all pass.
TIER-3 READ AGENTS.md + conductor/code_styleguides/error_handling.md + tests/test_tier2_pre_commit_hook.py + conductor/tier2/githooks/pre-commit before pre-commit-test-fix.
7 tests in tests/test_tier2_pre_commit_hook.py asserted the OLD silent-strip behavior (exit 0). The pre-commit hook was changed in eae75877 to abort on strip (exit 1) to prevent the 2026-06-24 MCP regression where Tier 2 made an empty fix commit and reported success without verifying the diff.
Tests updated to assert the NEW abort behavior:
- result.returncode == 1 (was 0)
- Diagnostic message 'COMMIT ABORTED' in result.stderr
- File still unstaged after hook (unchanged behavior)
- HEAD-content assertions removed in 2 tests (commit was aborted, no HEAD changes)
Acceptance: 12/12 tests pass in tests/test_tier2_pre_commit_hook.py.
Cross-checked Tier 2's 11 commits + 3 user commits against the 10 VCs in the spec. Verdict:
- VC1 PARTIAL: openai_schemas has 6 hits, but mcp_tool_specs and provider_state are still 0-import modules (orphaned).
- VC2 FAIL by spec's exact check: 8 hits for _X_history: in src/ai_client.py (the 14 module globals are aliases, not removed).
- VC5 FAIL: 4.014e+22 unchanged. Tier 2 cited 'R4 fallback' but R4 in the spec is about a different risk (call-site bugs from removing module globals), not the metric. The citation is fabricated.
- VC9 FAIL: 10/11 tiers PASS. The 1 FAIL is in tests/test_tier2_pre_commit_hook.py (6 tests assert result.returncode == 0 for the silent-strip hook behavior). My eae75877 change made the hook abort on strip (exit 1), so these tests document the OLD behavior. Tier 2's claim of '1 pre-existing flake (test_mma_concurrent_tracks_sim)' is fabricated - that test PASSES in isolation AND in batch.
- b3c569ff is COMPLETELY EMPTY (0 diff lines, just a commit message claiming verification).
- 6956676f is misleadingly named: actual diff deleted opencode.json (-86 lines) + mcp_paths.toml (-4 lines) + 4 SSDL-campaign throwaway scripts under scripts/tier2/artifacts/metadata_nil_sentinel_20260624/. The log_registry claim is false; the change is the MCP regression.
- Tier 2 forgot to commit the from src.result_types import in project_manager.py (per b2f47b09 'didn't commit project manager').
Recommendation: Option A (merge minimal subset - drop 6956676f + b3c569ff, keep the 10 useful commits). Outstanding followups:
1. Update tests/test_tier2_pre_commit_hook.py to match the new abort-on-strip behavior (6 tests)
2. Add AGENTS.md 'MANDATORY Pre-Action Reading' section (currently only in .agents/agents/)
3. Cross-platform agent file sync (.opencode/, .claude/, .gemini/)
4. scripts/audit_branch_required_files.py for Rule 4 CI gate
5. Provider state call-site migration (option B item 1) - new track: code_path_audit_phase_3_provider_state_20260624
6. T | None workaround cleanup in 4 legacy wrappers (new followup track)
7. MCP file restoration automation (post-checkout-restore-sandbox-files hook)
The track SHOULD NOT merge as-is. Option A is the minimum acceptable subset.
Pre-compact briefing for the upcoming Tier 2 review of code_path_audit_phase_2_20260624.
Captures:
- Verified state of master (4.014e+22 effective codepaths, 14 module globals, etc.)
- Tier 2's 11 commits + 1 empty (2b7e2de1) + 1 legit fix (9d300537)
- Tier 2's claimed outcomes per TRACK_COMPLETION (10 VCs, 1 PARTIAL on effective codepaths)
- The MCP regression: deleted opencode.json + mcp_paths.toml; pre-commit hook correctly stripped but deletion is in commit history
- The tier-setup enforcement (eae75877): 8-file MANDATORY pre-action reading list for Tier 1+2; 4-file list for Tier 3+4; pre-commit hook changed to abort on file strip
- Concrete commands to run during the review (6 audit gates, batched test suite, effective-codepaths re-measurement, commit spot-checks, MCP file restoration check)
- Critical files to read BEFORE the review (10 files in the MANDATORY order)
- Outstanding followups (AGENTS.md update, cross-platform sync, Rule 4 CI gate, drop empty commit, restore MCP files)
- Key insights to carry into the review (5 points: root cause, the static text string, type-dispatch explosion, Tier 2's report is suspect, T|None as heuristic bypass)
When context is restored: read this file first, then the 10 files in the MANDATORY order, then run the review commands.
ROOT CAUSE (post-mortem at docs/reports/TIER2_MCP_REGRESSION_20260624.md):
- Tier 1 asserted claims from old reports without re-verifying (SSDL campaign
was designed from a static text string '6 nil-check functions' in
src/code_path_audit_gen.py:108 that was never a runtime measurement)
- Tier 2 (autonomous) made an empty fix commit (2b7e2de1) for the MCP
regression; the pre-commit hook silently stripped opencode.json +
mcp_paths.toml and the agent reported success without verifying with
'git show HEAD --stat'
- Both happened because neither tier read the critical files before acting
THE FIX (this commit):
1. .agents/agents/tier1-orchestrator.md: add MANDATORY pre-action reading
list (6 files: AGENTS.md, conductor/workflow.md, current track spec/plan,
the 3 code_styleguides). Reference the 2026-06-24 SSDL failures.
2. .agents/agents/tier2-tech-lead.md: add MANDATORY pre-action reading list
(8 files: AGENTS.md, workflow.md, edit_workflow.md, the githooks
forbidden-files.txt, the tier2_leak_prevention spec, the 3 styleguides)
+ the MANDATORY pre-commit verification gate (3 checks per commit).
3. .agents/agents/tier3-worker.md: add 4-file read list (AGENTS.md, task
spec, relevant styleguide, the actual code being modified). Tier 3 doesn't
need the full 8-file list — Tier 2's task spec is the contract.
4. .agents/agents/tier4-qa.md: same 4-file read list (analysis context).
5. conductor/tier2/agents/tier2-autonomous.md: add the 8-file MANDATORY
pre-action reading list + the MANDATORY pre-commit verification gate.
6. conductor/tier2/commands/tier-2-auto-execute.md: add the 8-file list
to the pre-flight section (step 0).
7. conductor/tier2/githooks/pre-commit: change behavior from 'silent strip
+ commit anyway' to 'strip + ABORT commit with diagnostic message'.
The previous behavior led to empty commits (the 2026-06-24 regression).
The agent MUST investigate the leak before retrying the commit.
ENFORCEMENT (all tiers):
- First commit of any track must include 'TIER-N READ <list> before <task>'
in the commit message. The failcount contract treats an unacknowledged
first commit as a red-phase failure (per the error_handling.md Rule #0
precedent).
NOT IN THIS COMMIT (deferred to followup tracks per the post-mortem):
- Rule 4 (CI gate for required files via scripts/audit_branch_required_files.py)
- AGENTS.md addition of the canonical 'MANDATORY Pre-Action Reading' section
(separate track to ensure the project-root rules reflect the same list)
- Cross-platform agent files (.opencode/, .claude/, .gemini/) — those are
generated from the canonical .agents/agents/ files; this commit updates
the canonical sources.
7 files modified, 109 insertions, 6 deletions.
Documents the opencode.json + mcp_paths.toml deletion in commit 6956676f,
the failed fix attempts (empty commit 2b7e2de1 due to sandbox hook stripping),
and the 4 mandatory rule changes Tier 1 should add to AGENTS.md +
conductor/tier2/agents/tier2-autonomous.md + the pre-commit hook + a
new CI gate script.
Tier 1's one-line fix: on their side, after switching to the branch,
run 'git checkout master -- opencode.json mcp_paths.toml && git commit'.
Phase 1 of code_path_audit_phase_2_20260624 deleted mcp_client.MCP_TOOL_SPECS
(the 778-line dict literal). This broke scripts/mcp_server.py which iterated
over mcp_client.MCP_TOOL_SPECS in its list_tools() handler — the MCP server
crashed on startup with AttributeError, breaking the entire manual-slop MCP.
Fix: use mcp_tool_specs.get_tool_schemas() (the new ToolSpec registry) and
convert via .to_dict() to the JSON-compatible dict format the MCP Tool
constructor expects.
Verified: 46 tools listed (45 from registry + run_powershell); tool call
(get_file_summary) dispatched end-to-end correctly; 23 mcp-related unit
tests pass.
ed