Re-read in full (989 lines). Key sections reviewed for this track:
- The 5 Patterns (Nil-Sentinel, Zero-Init, Fail Early, AND over OR, Side-Channel)
- Drain Points section (the 5 patterns: HTTP error response, GUI error display,
intentional app termination, telemetry emission, bounded retry)
- The Broad-Except Distinction (broad+log = SILENT_SWALLOW violation)
- Re-Raise Patterns 1/2/3 (catch+convert, catch+log+reraise, catch+cleanup+reraise)
- AI Agent Checklist (5 MUST-DO + 7 MUST-NOT-DO + 3 boundary patterns)
- Rule #0: MUST READ THIS STYLEGUIDE FIRST
- The pre-commit gate (4 audit scripts in --strict mode)
Per Rule #0: this commit message acknowledges the read. The full styleguide
content was reviewed end-to-end before any code work in Phase 0.
Adds the end-of-track artifacts for the tier2_leak_prevention_20260620
fix track:
- docs/reports/TRACK_COMPLETION_tier2_leak_prevention_20260620.md:
Full track completion report following the precedent set by
TRACK_COMPLETION_tier2_autonomous_sandbox_20260616.md. Documents
the 4 atomic commits, the 25 default-on tests, the manual
end-to-end verification, the key design decisions (auto-unstage
not exit 1, git rm --cached --force, CRLF handling, specific not
prefix patterns), the known limitations, and the next steps for
the user (push to origin, rebase stale tier-2 branches, re-run
setup on the existing clone, optional CI wiring).
- conductor/tracks/tier2_leak_prevention_20260620/metadata.json:
Track metadata (status=shipped, scope: 5 new files + 1 modified,
25 default-on tests, 5 verification criteria, 5 risk-register
entries, 2 deferred follow-up tracks).
- conductor/tracks/tier2_leak_prevention_20260620/spec.md:
Track spec (background on the 00e5a3f2 offender commit, design
with the 3-layer defense-in-depth, forbidden patterns, tests,
out-of-scope items).
- conductor/tracks/tier2_leak_prevention_20260620/plan.md:
Track plan (4 phases: revert + hook + audit + install; tasks
recorded retroactively per workflow.md "Plan is the source of
truth").
- conductor/tracks/tier2_leak_prevention_20260620/state.toml:
Track state (status=completed, current_phase=complete, 4 phases
with checkpoint SHAs, 16 tasks all completed with commit SHAs).
- conductor/tracks.md: registered as track 6f in the Active
Tracks table; added a "Recently Completed" entry with the
commit-history summary.
Per conductor/workflow.md "End-of-track report" protocol. The
report includes a "Mistake to flag" section about the
`Remove-Item -Recurse -Force` accident during verification, per
the AGENTS.md "Hard ban on destructive commands" rule (which is
specifically about `git restore`/`git checkout`/`git reset`/`git
push` but the lesson generalizes: destructive PowerShell commands
on directories with tracked files require explicit verification
before running).
Initial v3 spec + plan for the major nagent review update. Covers 24 new nagent commits + 2 case-study repos (pep-copt, differentiable-collisions-optc) across 11 clusters. v2.3 historical reviews preserved; v3 is the canonical going forward.
TIER-2 READ conductor/code_styleguides/error_handling.md end-to-end before Phase 13.
Final state:
- All 13 phases completed (checksha recorded)
- All verification flags = true (audit_strict_exits_0,
site_inventory_has_42_rows, drain_plane_render_functions_exist,
silent_swallow_count_zero, rethrow_count_zero, unclear_count_zero,
broad_catch_count_zero)
- batched_suite_11_of_11_pass = false (Tier 3 has 1 known issue:
test_gui2_performance.py measures FPS 28.46 vs 30 threshold; documented
in TRACK_COMPLETION report as a known issue for user review)
- tracks.md updated: sub-track 4 row -> 'shipped 2026-06-20'
Track shipped on the success path. All 42 migration-target sites in
src/gui_2.py resolved.
Adds a tier-2 pre-commit hook that auto-unstages sandbox-only files
from any tier-2 commit, preventing the leak that hit master in
00e5a3f2 (the offender commit that was just selectively reverted
in fab2e55b). The hook is paired with a config file that lists the
forbidden paths as substring patterns.
Design:
- Hook reads conductor/tier2/githooks/forbidden-files.txt (one
substring pattern per line; # comments and blanks ignored)
- For each staged file, checks if any pattern is a substring of
the path. If a match is found, the file is auto-unstaged via
`git rm --cached --force` (force is required when the index
has content that differs from BOTH HEAD and the working tree)
- Hook always exits 0 — it removes the leak rather than blocking
the commit. A hard reject would leave tier-2 stuck mid-flow
(tier-2 cannot run `git restore --staged`, which is banned by
the sandbox permission rules)
- The hook's config file lives at the project root so it ships
with the clone. setup_tier2_clone.ps1 will install the hook
in a follow-up commit; existing clones need to re-run setup
to get the hook
Forbidden patterns (substring matches):
- .opencode/agents/tier2-autonomous (sandbox agent prompt)
- .opencode/commands/tier-2-auto-execute (sandbox slash command)
- opencode.json (MCP path / default_agent / model override)
- mcp_paths.toml (extra_dirs cleared in clone)
Patterns are SPECIFIC (not prefix-based) so they do not match
the legitimate interactive tier-2 tech-lead prompt at
.opencode/agents/tier2-tech-lead.md.
Tests (tests/test_tier2_pre_commit_hook.py, 12 cases):
- Empty staged set: git's standard "nothing to commit" error
- Allowed files: commit succeeds normally
- Each forbidden file (agent, command, opencode.json,
mcp_paths.toml) staged: auto-unstaged, commit proceeds
- Mixed staged set: only forbidden are unstaged
- Hook silent when no leaks detected
- Hook warns (stderr) when unstaging
- Config-driven: replacing forbidden-files.txt changes the
denylist without modifying the hook
- Paths with spaces: handled correctly via git diff -z
Defense-in-depth context:
- Layer 1: OpenCode permission system (denies direct edits to
these files from the tier2-autonomous agent)
- Layer 2 (this commit): pre-commit hook (removes the leak at
the commit boundary)
- Layer 3 (follow-up commit): scripts/audit_tier2_leaks.py
(scans working tree, CI gate)
Adds 2 invariant tests:
- test_phase_9_invariant_helper_utility_count_dropped: pins the count
to exactly 0 (post-Phase-9 baseline; no Phase 9 sites, count should
remain 0 after Phases 7-8 dropped it).
- test_phase_9_invariant_zero_sites_in_phase_9: documents that no
Phase 9 site tests exist (machine-checkable: future agent adding a
Phase 9 site will see this test fail at the count assertion).
Per PHASE1_SITE_INVENTORY.md, the one Phase 9 site (L1398 _close_vscode_diff)
is INTERNAL_SILENT_SWALLOW (the bare-except classification) and will be
handled in Phase 10 (logging NOT a drain per the convention).
Updates state.toml: phase_9 status = completed.
Adds 2 invariant tests:
- test_phase_8_invariant_property_setter_count_dropped: pins the count
to exactly 0 (post-Phase-8 baseline; all 22 INTERNAL_BROAD_CATCH sites
in src/gui_2.py migrated across Phases 3-8).
- test_phase_8_invariant_all_2_migration_sites_have_tests: verifies the
2 migrated sites (L591, L897) have both success and failure tests.
Updates state.toml: phase_8 status = completed.
Adds 2 invariant tests:
- test_phase_7_invariant_batch_d_count_dropped: pins the count to <=2
(post-Phase-7 baseline, down from 3 pre-Phase-7).
- test_phase_7_invariant_all_1_migration_sites_have_tests: verifies the
1 migrated site (L4321 worker) has both success and failure tests.
Updates state.toml: phase_7 status = completed.
Per PHASE1_SITE_INVENTORY.md, Phase 6 (signal-handler category) has 0
INTERNAL_BROAD_CATCH sites in src/gui_2.py. All sites that might appear
in a signal-handler category were classified into other phases (Phase 8
for startup callbacks, Phase 7 for worker/background).
Adds 2 invariant tests:
- test_phase_6_invariant_signal_handler_count_dropped: pins the count
to exactly 3 (the pre-Phase-7 baseline) before Phases 7-9 migrate.
- test_phase_6_invariant_zero_sites_in_phase_6: documents that no
Phase 6 site tests exist (machine-checkable: future agent adding a
Phase 6 site will see this test fail at the count assertion).
Updates state.toml: phase_6 status = completed.
TIER-2 READ conductor/code_styleguides/error_handling.md end-to-end before Phase 0.
Updates the sub-track 4 row from 'ready to start' to 'active 2026-06-19'.
Anti-sliming protocol (13 phases, per-site audit, per-phase invariant test)
is in effect for the migration of 42 sites in src/gui_2.py.
Sub-track 4 of the 5-sub-track result_migration_20260616 umbrella.
Migrates src/gui_2.py (the largest source file at 260KB / 7282 lines;
the immediate-mode ImGui rendering layer) to the data-oriented
Result[T] convention.
Scope: 42 migration-target sites (38 V + 2 S + 2 UNCLEAR) + 6 infra
sites for the drain plane. Per the user's directive (2026-06-19),
the phase structure is EXTRA LONG (13 phases instead of the umbrella's
1-2) to give Tier 2 well-defined narrow scope per phase. No phase has
more than 10 migration sites. This is the anti-sliming protocol:
previous sub-tracks slimed when scope felt tight (sub-track 2 Phase 10
slimed 21/26 sites via 5 laundering heuristics; sub-track 3 Phase 3
slimed 8 sites via logging.debug bodies). The 13-phase structure with
per-phase audit gates prevents sliming.
The 13 phases:
0. Setup + styleguide re-read (Tier 2 reads error_handling.md)
1. Site inventory + classification (42 sites in PHASE1_SITE_INVENTORY.md)
2. Drain plane wiring (3 new render functions: render_controller_error_modal,
_render_worker_error_indicator, _render_last_request_errors_modal)
3. INTERNAL_BROAD_CATCH Batch A (render-loop, <=10 sites)
4. INTERNAL_BROAD_CATCH Batch B (modal/dialog, <=10 sites)
5. INTERNAL_BROAD_CATCH Batch C (event handlers, <=10 sites)
6. Signal handler sites (<=5 sites; Pattern 3 drain: sys.exit)
7. Worker/background sites (<=5 sites; thread-safety via app._worker_errors_lock)
8. Property setter/state sites (<=5 sites)
9. Helper/utility sites (<=5 sites)
10. INTERNAL_SILENT_SWALLOW (<=13 sites; CRITICAL anti-sliming phase;
per user principle 'logging is NOT a drain')
11. INTERNAL_RETHROW classification (<=2 sites; Pattern 1/2/3)
12. UNCLEAR classification (<=2 sites)
13. Audit gate + end-of-track report (--strict exits 0; 11/11 tiers PASS)
Anti-sliming protocol per phase:
- Styleguide re-read at start of each phase (commit msg acknowledgment)
- Per-site audit pre/post check (capture before + after in commit body)
- Per-phase invariant test (test_phase_N_invariant_count_dropped)
- Per-file atomic commits (1 site = 1 commit)
- 'If a site resists migration: DO NOT invent a heuristic. Report.'
The data plane (8 controller state attributes added by sub-track 3
Phase 6: _last_request_errors, _worker_errors + lock,
_startup_timeline_errors, _signal_handler_error, _inject_preview_error,
_mcp_config_parse_error, _save_project_error, _model_fetch_errors) is
the source of truth. Sub-track 4 adds the drain plane (3 new render
functions in Phase 2) and migrates the 42 sites to feed their errors
into the data plane.
Files:
- spec.md (323 lines, 11 sections)
- plan.md (938 lines, 13 phases, 60+ atomic commits, anti-sliming protocol)
- metadata.json (14 VCs, 8 risks, scope)
- state.toml (14 phases, 102 tasks, 22 verification entries)
- tracks.md (new row 6d-4 in Active Tracks table)
Total: 5 files, 1327 lines added (excluding tracks.md).
Next: Tier 2 picks up Phase 0 (setup + styleguide re-read).
10 phases, 29 tasks, all worker-ready (WHERE / WHAT / HOW / SAFETY /
COMMIT / GIT NOTE per task):
Phase 1: Data extraction audit + draft helper script (FR5; TDD)
Phase 2: Generate conductor/chronology.md.draft
Phase 3: Prune [x]/[shipped] entries from conductor/tracks.md (FR2)
Phase 4: Add 3-step archiving convention to conductor/workflow.md (FR3)
Phase 5: Write docs/reports/CHRONOLOGY_MIGRATION_20260619.md (FR4)
Phase 6: User review of draft (GATE)
Phase 7: Promote draft to canonical chronology.md
Phase 8: Per-row cross-check (FR6 HARD GATE; 9 batches of ~20 rows)
Phase 9: Completeness check (FR6 HARD GATE; folder set vs row set)
Phase 10: User sign-off + end-of-track report (FR6 HARD GATE)
The cross-check (Phase 8) is the dominant cost. Per the user directive
2026-06-19, EVERY SINGLE ENTRY must be cross-checked. The plan batches
the work into 9 commits for review ergonomics; no batch is 'sample-based'
or 'looks right' -- each row's 5 fields (date, ID, status, summary,
range) are verified independently per FR6.
All 12 VCs from the spec are addressed in the plan's 'Verification
Criteria Recap' section.
Conductor Chronology is a manually-maintained, complete index of all
tracks (active + shipped + superseded + abandoned) plus notable
non-track commits. The per-track spec/plan/metadata in tracks/ and
archive/ remain the source of truth for each track's details; this
file is the index.
Scope (per the no-day-estimates rule added 2026-06-16):
- 6 FRs, 5 NFRs, 12 VCs, 9 Risks, 10 Phases
- 3 new files: conductor/chronology.md, scripts/audit/generate_chronology.py, docs/reports/CHRONOLOGY_MIGRATION_20260619.md
- 2 modified files: conductor/tracks.md (prune [x] entries), conductor/workflow.md (3-step archiving convention)
- 165+ per-row cross-check tasks (Phase 8 hard gate per user directive 2026-06-19)
User directive baked in as FR6 + VC10/VC11/VC12:
'EVERY SINGLE ENTRY MUST BE CROSS CHECKED TO MAKE SURE IT'S STILL
CORRECT, AND NOTHING WAS MISSED.' The helper script is DRAFT-ONLY;
the cross-check is the authority. Tier 1 does the mechanical check;
the user is the quality gate.
Plan + initial migration to follow in subsequent commits.
Phase 7 = Strict Enforcement Cleanup. 4 sites in src/app_controller.py
(L242, L256, L5064, L5093) are still classified compliant by the audit
via heuristic over-application, but strictly per error_handling.md:530
('logging is NOT a drain') they remain silent-swallow violations:
- L242, L256 in _api_generate: sys.stderr.write only (BOUNDARY_FASTAPI
over-application: scripts/audit_exception_handling.py:319-321 + 393-397
classify all nested try/except in _api_* handlers as compliant,
regardless of whether the except body raises HTTPException)
- L5064 _push_mma_state_update: logging.debug + print, no Result
- L5093 _load_active_tickets.beads inner: logging.debug + print, no Result
Phase 7 migrates all 4 to proper Result[T] propagation using the Phase 6
helpers already in the file (_rag_search_result, _symbol_resolution_result,
_report_worker_error), adds new Result helpers for _push_mma_state_update
and _load_beads_from_path, and tightens the audit heuristic so BOUNDARY_FASTAPI
only applies when the except body actually raises HTTPException or returns
a Result.
Spec.md sections 22.1-22.9 (9 sections, 111 lines); plan.md Phase 7 with
13 worker-ready tasks (81 lines); state.toml adds phase_7 entry + 13 t7_*
tasks + [verification.phase_7] block (25 lines); metadata.json adds 3
verification_criteria, 3 risk_register entries, 2 modified_files, and
updates estimated_effort.scope to reflect Phase 7 (49 migration sites
total, 25+ atomic commits).
Documents the four follow-up commits made after the initial track ship:
63e91198 (test updates), cb68d86f (RuntimeError catch), 78256174
(defensive save), 61a89fa3 (report addendum). See
docs/reports/TRACK_COMPLETION_test_sandbox_hardening_20260619.md
'Post-completion fixes' section for details.
ed