conductor(track): init enforcement_gap_closure_20260627

Spec + plan + metadata + state for the enforcement-gap closure track.
Two pieces: (1) new scripts/audit_boundary_layer.py + allowlist to enforce
the section 17.7 'no dict[str, Any] outside the wire boundary' rule; (2) rename
audit_optional_in_3_files.py -> audit_optional_returns.py and widen from 4
baseline files to all src/*.py (baselining 3 history.py residuals).

Parallel-safe against tier2/post_module_taxonomy_de_cruft_20260627: zero file
overlap (touches only scripts/audit_*, scripts/*.toml, python.md, new tests).
Closes contradictions C1, C2, C3-partial, C18-partial, C21 from
docs/reports/CONTRADICTIONS_REPORT_20260627.md. The 14 docs-sync
contradictions (C5-C9, C16, C17, C11-C15, C19, C20) deferred per user
directive until the tier2 taxonomy branch stabilizes.

conductor/tracks/enforcement_gap_closure_20260627/metadata.json

@@ -0,0 +1,109 @@
+{
+ "track_id": "enforcement_gap_closure_20260627",
+ "name": "Enforcement Gap Closure (Boundary-Layer Audit + Optional[T] Audit Widening)",
+ "status": "active",
+ "branch": "master",
+ "created": "2026-06-27",
+ "owner": "Tier 1 (initialized); implementation delegated to Tier 2/3.",
+ "blocked_by": [],
+ "blocks": [],
+ "scope": {
+  "new_files": [
+   "scripts/audit_boundary_layer.py",
+   "scripts/boundary_layer_allowlist.toml",
+   "scripts/audit_optional_returns.py (renamed from audit_optional_in_3_files.py)",
+   "scripts/audit_optional_returns.baseline.json",
+   "tests/test_audit_boundary_layer.py",
+   "tests/test_audit_optional_returns.py",
+   "docs/reports/TRACK_COMPLETION_enforcement_gap_closure_20260627.md"
+  ],
+  "modified_files": [
+   "conductor/code_styleguides/python.md (sections 17.7, 17.8, inventory table 449-456)",
+   "conductor/code_styleguides/error_handling.md (cross-reference sweep only)",
+   "docs/AGENTS.md (cross-reference sweep only)",
+   "conductor/tracks.md (active-track row + status)",
+   "conductor/chronology.md (prepend shipment row)"
+  ],
+  "deleted_files": [
+   "scripts/audit_optional_in_3_files.py (renamed to audit_optional_returns.py via git mv)"
+  ]
+ },
+ "estimated_effort": {
+  "method": "scope (per workflow.md Tier 1 Track Initialization Rules. NO day estimates.)",
+  "phase_1": "4 tasks: 1 test file (10 tests) + 1 audit script + 1 allowlist TOML + green-phase verification",
+  "phase_2": "3 tasks: 1 test file (5 tests) + 1 rename/edit + 1 baseline JSON + green-phase verification",
+  "phase_3": "2 tasks: 1 styleguide inventory edit + 1 cross-reference sweep",
+  "phase_4": "4 tasks: 7-audit verification + 1 end-of-track report + 1 state update + user sign-off"
+ },
+ "verification_criteria": [
+  "G1: scripts/audit_boundary_layer.py exists + AST-scans all src/*.py + exits 1 in --strict on un-allowlisted dict[str, Any] sites",
+  "G2: scripts/boundary_layer_allowlist.toml exists + lists ~14 boundary files with reasons + --show-allowlist prints them",
+  "G3: scripts/audit_optional_returns.py exists (renamed from audit_optional_in_3_files.py) + scans all src/*.py + 3 history.py residuals baselined in audit_optional_returns.baseline.json (strict stays green)",
+  "G4: conductor/code_styleguides/python.md sections 17.7, 17.8, and inventory table reflect post-track reality (audit_boundary_layer implemented; audit_optional_returns implemented; audit_imports implemented)",
+  "G5: cross-reference sweep complete (no enforcement-instruction references to audit_optional_in_3_files.py; historical references preserved)",
+  "G6: tests/test_audit_boundary_layer.py has >=10 tests; all pass",
+  "G7: tests/test_audit_optional_returns.py has >=5 tests; all pass",
+  "G8: docs/reports/TRACK_COMPLETION_enforcement_gap_closure_20260627.md exists; documents contradiction closure (C1, C2, C3-partial, C18-partial, C21) and remaining (C5, C6, C16, C17 - deferred per user directive)",
+  "VC_pre_commit_parallel_safe": "ZERO file overlap with the running tier2/post_module_taxonomy_de_cruft_20260627 branch (verified by Tier 1 against ddcec7b0 + TRACK_COMPLETION file-level changes)"
+ ],
+ "regressions_and_pre_existing_failures": [],
+ "pre_existing_failures_remaining": [],
+ "deferred_to_followup_tracks": [
+  {
+   "title": "Optional[T] return migration in src/history.py",
+   "description": "3 RETURN_OPTIONAL sites in src/history.py baselined by this track; cruft_elimination_20260627 Phase 6 owns the migration to Result[T] + NIL_T.",
+   "track_status": "planned in cruft_elimination_20260627"
+  },
+  {
+   "title": "dict[str, Any] migration in hot_reloader.py + startup_profiler.py",
+   "description": "2 un-allowlisted boundary violations baselined by this track; a future track promotes them to typed dataclasses (HotReloadSnapshot, ProfilerSnapshot).",
+   "track_status": "not yet initialized"
+  },
+  {
+   "title": "Main-repo pre-commit hook wiring",
+   "description": "The 5 audit scripts strict mode (weak_types, boundary_layer, optional_returns, exception_handling, imports) is not wired into the main repo's .git/hooks/. Per contradictions report C4.",
+   "track_status": "not yet initialized"
+  },
+  {
+   "title": "Docs-count drift in docs/Readme.md (C7, C8, C9) + styleguide drift (C16 python.md s10, C17 type_aliases.md line 19) + RAGChunk.id in guides (C6)",
+   "description": "Deferred per user directive 2026-06-27 until tier2 branch stabilizes; these describe code state that exists post-merge of the taxonomy branches.",
+   "track_status": "deferred; will bundle into a docs-sync track post-merge"
+  }
+ ],
+ "risk_register": [
+  {
+   "id": "R1",
+   "description": "audit_optional_returns.baseline.json format mismatch with audit_weak_types.baseline.json contract",
+   "likelihood": "medium",
+   "impact": "the renamed --strict mode behaves inconsistently with the existing baseline pattern",
+   "mitigation": "Tier 3 reads scripts/audit_weak_types.py + its baseline JSON before implementing; mirror the exact contract"
+  },
+  {
+   "id": "R2",
+   "description": "Cross-file rename race if Tier 2 branch touches scripts/audit_optional_in_3_files.py in parallel",
+   "likelihood": "low",
+   "impact": "the git mv conflicts with Tier 2 work",
+   "mitigation": "Tier 1 verified post_module_taxonomy_de_cruft TRACK_COMPLETION does not touch audit_optional_*; only scripts/audit_no_models_config_io.py"
+  },
+  {
+   "id": "R3",
+   "description": "Boundary allowlist under-classifies a genuine violation as boundary (false negative)",
+   "likelihood": "medium",
+   "impact": "the audit misses a real dict[str, Any] escape hatch that future LLMs reach for",
+   "mitigation": "Tier 1's spec 'Current State Audit' manually classified the 14 legitimate boundary files + 2 genuine violators; the audit starts from that classification. Reviewer (user) inspects boundary_layer_allowlist.toml before merge."
+  },
+  {
+   "id": "R4",
+   "description": "Over-classification: audit flags a genuine boundary function as a violation (false positive)",
+   "likelihood": "low",
+   "impact": "strict mode is red on a real boundary file; either the allowlist is amended (correct fix) or the violation is suppressed (wrong fix, masks drift)",
+   "mitigation": "Per spec FR1, allowlisting is the explicit 'declare your boundary' mechanism; the reviewer audits the allowlist at merge time. The audit's `--no-allowlist` mode exposes every site so reviewers can spot-check classifications."
+  }
+ ],
+ "contradictions_report_cross_reference": {
+  "source": "docs/reports/CONTRADICTIONS_REPORT_20260627.md",
+  "closes": ["C1", "C2", "C3_partial", "C18_partial", "C21"],
+  "defers": ["C5", "C6", "C7", "C8", "C9", "C11", "C12", "C13", "C14", "C15", "C16", "C17", "C19", "C20"],
+  "rationale": "C1+C2+C21 are about the Optional audit name+scope (closed by Phase 2 rename+widen). C3-partial is 'audit_imports.py planned but exists' (closed by Phase 3 inventory correction). C18-partial is the audit count (closed by Phase 3). The 14 deferred items are docs-sync (C5-C9, C16, C17) or status drift (C11-C15, C19, C20) that per user directive 2026-06-27 wait for the tier2 taxonomy branch to stabilize before touching master's docs."
+ }
+}

conductor/tracks/enforcement_gap_closure_20260627/plan.md

@@ -0,0 +1,172 @@
+# Plan: Enforcement Gap Closure (Boundary-Layer Audit + Optional[T] Audit Widening)
+
+Track: `enforcement_gap_closure_20260627`
+Branch: master (parallel-safe against `tier2/post_module_taxonomy_de_cruft_20260627`)
+Spec: `conductor/tracks/enforcement_gap_closure_20260627/spec.md`
+
+This plan is read by a Tier 3 Worker (or Tier 2). All Python edits MUST use 1-space indentation. No comments in body. CRLF preserved via `manual-slop_edit_file` MCP tool (never native `edit`).
+
+**Audit-then-specify verification done by Tier 1:** All file:line references below were verified against master at `77b70226` on 2026-06-27.
+
+---
+
+## Phase 1: Boundary-Layer Audit Script
+
+Focus: Implement `scripts/audit_boundary_layer.py` + `scripts/boundary_layer_allowlist.toml` + tests, mirroring the `audit_imports.py` + `audit_imports_whitelist.toml` contract.
+
+- [ ] Task 1.1: Write failing tests for `scripts/audit_boundary_layer.py`
+  - **WHERE:** `tests/test_audit_boundary_layer.py` (NEW file)
+  - **WHAT:** 10 tests per spec FR5 (finder detects `dict[str, Any]` in return / param / local; allowlist suppression + WHITELISTED annotation; `--strict` exit 1 on un-allowlisted; `--strict` exit 0 on allowlisted; `--json` shape; missing-file handling; syntax-error handling; `--show-allowlist`).
+  - **HOW:** Use `tmp_path` (or `tests/artifacts/` per workspace_paths.md — see workflow.md "Test Sandbox Hardening") to create a synthetic `src/` tree the audit can scan via a `--src` flag (mirror `audit_weak_types.py --src`). Each test creates 1-2 small .py files with the pattern under test, invokes the audit via `subprocess.run(["python", "scripts/audit_boundary_layer.py", "--src", str(tmp_src), ...])`, asserts on stdout + exit code. Tests MUST fail before the script exists (Red phase).
+  - **SAFETY:** No `live_gui` fixture (these are unit tests of a script). No `unittest.mock.patch` of core code. Use `monkeypatch.setenv` for the `--src` path or pass via argv.
+  - **COMMIT:** `test(audit): add 10 failing tests for boundary-layer audit`
+  - **GIT NOTE:** Red-phase tests for `scripts/audit_boundary_layer.py`; cover finder + allowlist + strict + json + error-handling per spec FR1 + FR5.
+
+- [ ] Task 1.2: Implement `scripts/audit_boundary_layer.py`
+  - **WHERE:** `scripts/audit_boundary_layer.py` (NEW file)
+  - **WHAT:** Implement the audit per spec FR1. The structure mirrors `scripts/audit_imports.py` (309 lines): module docstring → argparse → `audit_file(path) -> list[Finding]` → main loop over `sorted(Path(src).glob("*.py"))` → exit code logic.
+  - **HOW:** Reuse the `audit_optional_in_3_files.py` AST detector pattern (it already has `_annotation_is_optional_arg` — copy the analogous `_is_dict_str_any` helper). Detection contract (FR1):
+    1. Walk each `ast.FunctionDef` / `AsyncFunctionDef`:
+       - If `node.returns` is `dict[str, Any]` (Subscript with value Name "dict"|"Dict" and slice Tuple `[Name "str", Name "Any"]`) → emit `RETURN_DICT_ANY`.
+       - For each arg in `args.args + kwonlyargs + posonlyargs`: if `arg.annotation` is `dict[str, Any]` → emit `PARAM_DICT_ANY`.
+    2. Walk each `ast.AnnAssign` inside a function body: if `target.annotation` is `dict[str, Any]` → emit `LOCAL_ANNOT_DICT_ANY`.
+    3. Allowlist: load `scripts/boundary_layer_allowlist.toml` (use `tomllib.load`); for any file whose relative path is a key, suppress all findings for that file and emit a single `WHITELISTED` finding per file (matches `audit_imports.py` precedent).
+    4. CLI flags: `--strict`, `--json`, `--show-allowlist`, `--no-allowlist`, `--src <path>` (default `"src"`).
+    5. Default mode: print summary table (file, sites, allowlisted) + a list of violations; exit 0.
+    6. `--strict`: same + exit 1 if there are un-allowlisted `RETURN_DICT_ANY` / `PARAM_DICT_ANY` / `LOCAL_ANNOT_DICT_ANY` findings.
+    7. `--json`: print JSON `{files_scanned, files_with_findings, total_findings, by_kind, findings}` and exit 0.
+    8. `--show-allowlist`: print the TOML contents + reasons; exit 0.
+    9. `--no-allowlist`: do not read the TOML; audit all sites.
+  - **SAFETY:** Pure stdlib (`ast`, `argparse`, `json`, `sys`, `pathlib.Path`, `tomllib`). No subprocess to `src/` files.
+  - **COMMIT:** `feat(audit): implement audit_boundary_layer.py per FR1`
+  - **GIT NOTE:** Implements the §17.7 boundary-layer audit; mirrors audit_imports.py contract; allowlist-driven per-file suppression.
+
+- [ ] Task 1.3: Write `scripts/boundary_layer_allowlist.toml`
+  - **WHERE:** `scripts/boundary_layer_allowlist.toml` (NEW file)
+  - **WHAT:** Initial allowlist with the ~14 legitimate boundary files from spec "Current State Audit": `context_presets.py`, `events.py`, `openai_compatible.py`, `theme_models.py`, `log_registry.py`, `presets.py`, `tool_presets.py`, `personas.py`, `workspace_manager.py`, `paths.py`, `gemini_cli_adapter.py`, `mcp_client.py`, `type_aliases.py`, `session_logger.py`.
+  - **HOW:** Mirror `audit_imports_whitelist.toml` format:
+    - Header comment block (purpose + format).
+    - "Last reviewed: 2026-06-27"
+    - One `[allowlist."<relative_path>"]` entry per file with `reason = "..."` documenting why it's at the wire boundary (the reasons are documented in spec "Current State Audit" — e.g., context_presets = "project_dict is the wire TOML"; events.to_dict = "wire serialization for WS protocol"; etc.).
+  - **SAFETY:** Pure TOML; no code.
+  - **COMMIT:** `feat(audit): seed boundary_layer_allowlist.toml with 14 boundary files`
+  - **GIT NOTE:** Allowlist seeds the §17.7 legitimate boundary; per audit_imports_whitelist.toml precedent.
+
+- [ ] Task 1.4: Run tests for Phase 1 (Green phase)
+  - **WHAT:** Execute `uv run pytest tests/test_audit_boundary_layer.py -v` (batched-runner convention can also be used: `uv run python scripts/run_tests_batched.py --filter test_audit_boundary_layer`). All 10 tests must pass. If any fail, debug (≤2 retries per workflow.md "Deduction Loop" rule), then STOP and report if still failing.
+  - **COMMIT:** `conductor(state): mark Phase 1 task 1.4 verification` (or skip the commit if no code changes; just verify).
+  - **GIT NOTE:** Green-phase verification for boundary-layer audit + allowlist.
+
+---
+
+## Phase 2: Optional[T] Audit Rename + Widening
+
+Focus: Rename `audit_optional_in_3_files.py` → `audit_optional_returns.py`, widen from 4 files to all `src/*.py`, baseline the 3 `history.py` residuals.
+
+- [ ] Task 2.1: Write failing tests for the renamed + widened audit
+  - **WHERE:** `tests/test_audit_optional_returns.py` (NEW file)
+  - **WHAT:** 5 tests per spec FR5: test_renamed_script_exists, test_scans_all_src_files, test_baseline_reading_keeps_strict_green, test_strict_exits_1_above_baseline, test_param_optional_is_warning_not_strict.
+  - **HOW:** For test_scans_all_src_files, use `monkeypatch` + `--src <tmp_src>` flag (the script may need a `--src` flag added in Task 2.2 if it doesn't already have one — current `audit_optional_in_3_files.py` hardcodes the 4-file path; Task 2.2 adds `--src`). Tests must fail against the OLD script (which still hardcodes 4 files).
+  - **SAFETY:** No `live_gui`. No core mocking.
+  - **COMMIT:** `test(audit): add 5 failing tests for audit_optional_returns widening`
+  - **GIT NOTE:** Red-phase tests for the rename + widening to all src/*.py per spec FR3 + FR5.
+
+- [ ] Task 2.2: Rename + widen `audit_optional_in_3_files.py` → `audit_optional_returns.py`
+  - **WHERE:** `git mv scripts/audit_optional_in_3_files.py scripts/audit_optional_returns.py` then edit the new file.
+  - **WHAT:** Per spec FR3:
+    1. `git mv` the file (preserves history).
+    2. Edit `scripts/audit_optional_returns.py`:
+       - Module docstring: drop "4 baseline files"; say "all `src/*.py` per §17 post-2026-06-27 widening (the successor to `audit_optional_in_3_files.py`, which was renamed + widened on 2026-06-27)."
+       - Replace `BASELINE_FILES: tuple[str, ...] = (...)` with `def _discover_src_files(src_dir: str = "src") -> list[Path]: return sorted(Path(src_dir).glob("*.py"))`.
+       - Update `main()` to iterate `_discover_src_files(args.src)` instead of the hardcoded tuple.
+       - Add `--src <path>` arg (default `"src"`) mirroring `audit_weak_types.py`.
+       - Update `--json` output's `"files_scanned"` field to reflect the glob count.
+    3. Create `scripts/audit_optional_returns.baseline.json` recording the 3 `src/history.py` `RETURN_OPTIONAL` findings so `--strict` exits 0 on master (findings ≤ baseline). Format: same as `audit_weak_types.baseline.json` (a JSON object with a count or a list of `{file, line, function, kind}` entries that strict mode subtracts). The strict-mode logic: load baseline; subtract baseline findings from current findings; exit 1 if residuals > 0. (Mirror `audit_weak_types.py`'s `--strict` + baseline contract — read its source to confirm the exact subtraction mechanism.)
+  - **SAFETY:** No `src/` edits. No tests/ edits except the new test file from Task 2.1.
+  - **COMMIT:** `refactor(audit): rename audit_optional_in_3_files.py -> audit_optional_returns.py; widen to all src/*.py; baseline 3 history.py residuals`
+  - **GIT NOTE:** Closes contradictions C1+C21 (script name) + C2 (Optional ban scope ambiguity); script name + scope + baseline now honest per §17 post-2026-06-27.
+
+- [ ] Task 2.3: Run tests for Phase 2 (Green phase)
+  - **WHAT:** `uv run pytest tests/test_audit_optional_returns.py -v`. All 5 tests must pass. If failures, ≤2 debug retries; then STOP.
+  - **VERIFY:** Also run the existing audit_optional tests (if any reference the old name, update them — likely there are no callers other than `code_path_audit_20260607`'s historical references which don't run).
+  - **COMMIT:** `conductor(state): mark Phase 2 task 2.3 verification` (or skip if no code changes).
+  - **GIT NOTE:** Green-phase verification for the rename + widening.
+
+---
+
+## Phase 3: Styleguide Doc Reconciliation
+
+Focus: Fix `python.md` §17 enforcement inventory + §17.8 section to match post-track reality. Close contradictions C3, C18 (audit_imports exists), C1+C21 (script renamed), C2 (scope clarified), C5 (Result notation — only if no branch-sensitivity; per spec OOS, this is C5 which is deferred — confirm during this phase).
+
+- [ ] Task 3.1: Fix `python.md` §17 inventory table (lines 449-456) + §17.8 enforcement section (lines 357-362)
+  - **WHERE:** `conductor/code_styleguides/python.md`
+  - **WHAT:** Per spec FR4:
+    1. Inventory table (lines 449-456): update the rows:
+       - `dict[str, Any]` ban: ADD a row for `scripts/audit_boundary_layer.py --strict` (implemented this track; reads `boundary_layer_allowlist.toml`; `--no-allowlist` audits all). KEEP the existing `audit_weak_types.py --strict` row (they catch overlapping but distinct shapes — weak_types catches `Any` in any position; boundary_layer specifically targets `dict[str, Any]` in *signatures* outside the allowlisted boundary).
+       - `Optional[T]` returns: change the row from "audit_optional_in_3_files.py covering 4 baseline files" to "audit_optional_returns.py --strict covering all src/*.py; reads audit_optional_returns.baseline.json for the 3 history.py residuals until cruft_elimination Phase 6". Mark "✅ implemented".
+       - Local imports + `_PREFIX` aliasing + repeated `.from_dict()`: change `audit_imports.py` row to "✅ implemented" (was "⚠️ not yet built" — wrong; the script exists at `scripts/audit_imports.py`).
+       - Repeated `.from_dict()`: drop "(no script planned; relies on Tier 2 review)" — covered by `audit_imports.py`.
+    2. §17.8 enforcement section (lines 357-362): rewrite the bullets per spec FR4:
+       - Bullet for `audit_optional_returns.py` → reflects rename + all-src scope.
+       - Bullet for `audit_imports.py` → drop the "(planned per §17.9a)" parenthetical; mark as implemented.
+       - Bullet for `audit_boundary_layer.py --strict` → replace the "boundary_layer audit (planned...)" bullet; describe the script + allowlist + `--no-allowlist` flag.
+       - The "Pre-commit: every commit MUST pass all four audits above" line → "five audits above" (weak_types, boundary_layer, optional_returns, exception_handling, imports).
+  - **HOW:** Use `manual-slop_edit_file` MCP tool. Verify exact line ranges via `manual-slop_get_file_slice` before editing (the line numbers above are approximate; the actual edit replaces a contiguous block). Preserve CRLF.
+  - **SAFETY:** Pure doc edit. No code. No `src/` changes. No tests changes.
+  - **COMMIT:** `docs(python.md): reconcile §17 inventory + §17.8 with post-track reality`
+  - **GIT NOTE:** Closes C3 (audit_imports.py was "planned" but exists), C18 (audit count), C1+C21 reflected in doc; C2 scope clarified.
+
+- [ ] Task 3.2: Cross-reference sweep for `audit_optional_in_3_files.py` references
+  - **WHAT:** Use `manual-slop_py_find_usages` / `rg` to find ALL references to the old script name across `conductor/` and `docs/`. Per the spec, references likely exist in `error_handling.md:885` + `docs/AGENTS.md §"Convention Enforcement"`. For each reference:
+    - If it's a historical/cross-reference note (e.g., "was `audit_optional_in_3_files.py`"), leave it.
+    - If it's an enforcement-instruction reference (e.g., "run `uv run python scripts/audit_optional_in_3_files.py --strict`"), update to `audit_optional_returns.py`.
+  - **COMMIT:** `docs: update audit_optional_in_3_files.py references to audit_optional_returns.py`
+  - **GIT NOTE:** Historical references preserved (the rename history is documented in python.md:359); enforcement instructions updated.
+
+---
+
+## Phase 4: End-of-Track Report + State Update
+
+- [ ] Task 4.1: Run the full 7-audit strict suite (gate verification)
+  - **WHAT:** Execute all 7 audit scripts (now including the 2 new ones this track ships) in `--strict` mode:
+    ```
+    uv run python scripts/audit_weak_types.py --strict
+    uv run python scripts/audit_boundary_layer.py --strict
+    uv run python scripts/audit_optional_returns.py --strict
+    uv run python scripts/audit_exception_handling.py --strict
+    uv run python scripts/audit_imports.py --strict
+    uv run python scripts/audit_main_thread_imports.py
+    uv run python scripts/audit_no_models_config_io.py
+    ```
+    Expected: all pass (the boundary audit's 2 residuals `hot_reloader.py` + `startup_profiler.py` MUST be in the baseline JSON or the allowlist — verify before this step). The Optional audit's 3 `history.py` residuals are in `audit_optional_returns.baseline.json` (created in Phase 2).
+  - **VERIFY:** If any audit fails, fix the baseline OR the allowlist. Do NOT mask a real violation; document the residual in the end-of-track report instead.
+  - **COMMIT:** `test(audit): verify all 7 audit gates pass --strict post-track`
+  - **GIT NOTE:** The 7-audit strict suite green; the 2 boundary + 3 Optional residuals baselined per spec.
+
+- [ ] Task 4.2: Write end-of-track report
+  - **WHERE:** `docs/reports/TRACK_COMPLETION_enforcement_gap_closure_20260627.md` (NEW file)
+  - **WHAT:** Report following the precedent of `TRACK_COMPLETION_post_module_taxonomy_de_cruft_20260627.md`:
+    - TL;DR
+    - Phase summary (each phase + commits + status)
+    - Verification Criteria status (mapped to spec G1-G8)
+    - File-level changes (new + modified + renamed + new test files)
+    - Commits log (atomic, ordered)
+    - Audit gate status (all 7)
+    - Contradictions closed (C1, C2, C3-partial, C18-partial, C21) and remaining (C5, C6, C16, C17 — deferred per user directive; cite spec OOS)
+    - Known residuals: 2 boundary (`hot_reloader.py`, `startup_profiler.py`) + 3 Optional (`src/history.py`); these are baselined + owned by future tracks
+    - Next steps for the user (review + the recommended follow-up track)
+  - **COMMIT:** `docs(reports): TRACK_COMPLETION_enforcement_gap_closure_20260627`
+  - **GIT NOTE:** End-of-track report; documents contradiction closure + residual baselines.
+
+- [ ] Task 4.3: Update `conductor/tracks.md` + `conductor/chronology.md` + `conductor/tracks/enforcement_gap_closure_20260627/state.toml`
+  - **WHAT:**
+    1. `state.toml`: mark all phases "completed" with their checkpoint SHA; set `status = "completed"` + `current_phase = "complete"`.
+    2. `conductor/tracks.md`: add a row to the Active Tracks table for this track (status "shipped"); or per the convention of recent tracks, the row is added when the track is initiated and the status updated when shipped.
+    3. `conductor/chronology.md`: prepend a row for `2026-06-27 | enforcement_gap_closure_20260627 | shipped | summary...` at the top of the table.
+  - **COMMIT:** `conductor(state): enforcement_gap_closure_20260627 SHIPPED + TRACK_COMPLETION`
+  - **GIT NOTE:** Track state + chronology + tracks.md closed out.
+
+- [ ] Task 4.4: Conductor - User Manual Verification (Protocol in workflow.md)
+  - **WHAT:** Per the workflow.md "Phase Completion Verification and Checkpointing Protocol", present the results to the user for confirmation. Present: the 7-audit strict pass result, the test count, the contradictions closed, and the residual baselines. PAUSE for user sign-off.
+  - **COMMIT:** (no commit; this is the user-confirmation gate)
+  - **GIT NOTE:** User sign-off record.

conductor/tracks/enforcement_gap_closure_20260627/spec.md

@@ -0,0 +1,433 @@
+# Track Specification: Enforcement Gap Closure (Boundary-Layer Audit + Optional[T] Audit Widening)
+
+## Overview
+
+Close the two genuine enforcement gaps in the 7-banned-pattern mandate documented in
+`conductor/code_styleguides/python.md` §17 (the LLM Default Anti-Patterns):
+
+1. **The boundary-layer audit** — the script that enforces "no `dict[str, Any]`
+   outside the 2-3 wire-parse functions per file" (`python.md` §17.7). Currently
+   marked "⚠️ not yet built" in the §17 enforcement inventory (`python.md:454`),
+   though the cruft_elimination_20260627 Phase 10 only produced a *report*
+   (`docs/reports/boundary_layer_20260628.md`) — never the *audit script*. This
+   is the one that prevents the next LLM from reaching for `dict[str, Any]` in
+   `app_controller.py` again.
+
+2. **The `audit_optional_in_3_files.py` rename + widening** — the script
+   currently named `audit_optional_in_3_files.py` actually checks 4 files
+   (the contradictions report C1+C21) and only enforces the `Optional[T]` ban
+   on those 4 baseline files. `python.md:359` already references a successor
+   `audit_optional_returns.py` (claimed "✅ implemented" in the inventory at
+   `python.md:452`) but the rename never happened and the script never widened
+   to all `src/*.py`. This track lands reality on both the script and the doc.
+
+Both pieces are parallel-safe against the running `post_module_taxonomy_de_cruft_20260627`
+Tier 2 work: this track touches only `scripts/audit_*`, `scripts/*.toml` (allowlists),
+`conductor/code_styleguides/python.md` (the inventory table), and new `tests/test_*`
+files. Zero overlap with `src/models.py`, `tests/test_models*`, `src/api_hooks.py`,
+`scripts/audit_no_models_config_io.py`, or anything else Tier 2 is modifying.
+
+## Current State Audit (as of master `77b70226`, branch `tier2/post_module_taxonomy_de_cruft_20260627` `ddcec7b0`)
+
+### Already Implemented (DO NOT re-implement)
+
+- `scripts/audit_weak_types.py` (388 lines) — flags `dict[str, Any]`, `Any`,
+  anonymous tuple returns; informational default + `--strict` CI gate; reads
+  `scripts/audit_weak_types.baseline.json`. **Implemented, working.** Covers
+  §17.1 (`dict[str, Any]` / `Any` ban) and §17.2 (anonymous tuples) globally.
+
+- `scripts/audit_exception_handling.py` (~500 lines) — classifies
+  `try/except/finally/raise` sites into 10 categories; informational default +
+  `--strict` CI gate. **Implemented, working.** Covers §17.3 (silent swallow /
+  broad catch) globally.
+
+- `scripts/audit_imports.py` (309 lines) — flags local imports (§17.9a),
+  `_PREFIX` aliasing (§17.9b), and repeated `.from_dict()` (§17.9c);
+  informational default + `--strict` CI gate; reads
+  `scripts/audit_imports_whitelist.toml` for vendor-SDK-warmup + hot-reload
+  per-file exemptions. **Implemented, working** (despite `python.md:455-456`
+  marking it "not yet built" — a doc drift this track fixes). Covers §17.9
+  fully.
+
+- `scripts/audit_imports_whitelist.toml` (81 lines) — per-file whitelist with
+  `reason` field + "Last reviewed" header. **The precedent template** for the
+  new `boundary_layer_allowlist.toml` this track creates.
+
+- `scripts/audit_optional_in_3_files.py` (122 lines) — AST-scans 4 files
+  (`src/mcp_client.py`, `src/ai_client.py`, `src/rag_engine.py`,
+  `src/code_path_audit.py`); the `BASELINE_FILES` tuple at line 17-22 is the
+  only thing pinning it to those files; the audit logic is generic
+  (`_return_annotation_is_optional`, `_annotation_is_optional_arg`,
+  `audit_file`). **Implementation 100% reusable; only the file glob +
+  name + docs need to change.**
+
+### Gaps to Fill (This Track's Scope)
+
+- **GAP-1: No boundary-layer audit script exists.** `python.md:454` and
+  `python.md:361` mark it "planned / not yet built". The
+  `cruft_elimination_20260627` spec describes it at FR1 §72 ("Boundary Layer
+  is EXACTLY 2 places") and G14 ("boundary layer is documented as exactly 2
+  places") but only ever delivered a *report* (`boundary_layer_20260628.md`),
+  never a *static audit*. Without this, the §17.7 contract ("2-3 boundary
+  functions per file, everything else must be typed") is policy-without-teeth.
+
+- **GAP-2: `audit_optional_in_3_files.py` name lies + scope is too narrow.**
+  - It actually checks 4 files (mcp_client, ai_client, rag_engine,
+    code_path_audit) but is named "_3_files".
+  - It only covers those 4 baseline files. The §17 mandate requires
+    `Optional[T]` return-types banned in *all* `src/*.py`.
+  - `python.md:359` + `python.md:452` already promise an
+    `audit_optional_returns.py` "covering all `src/*.py`" — but no such
+    script exists. The doc claims reality that the code doesn't match.
+
+- **GAP-3: `python.md` §17 inventory table is internally inconsistent.**
+  Lines 451-456 mark `audit_imports.py` as "not yet built" (false — it exists)
+  and `audit_optional_returns.py` as "implemented" (false — it doesn't exist;
+  only the `audit_optional_in_3_files.py` does). This track corrects both rows
+  to match post-track reality.
+
+### Verified `dict[str, Any]` Distribution on master (the blast-radius for GAP-1)
+
+Per the audit-style AST scan I ran on master at `77b70226` (full scan of all
+`src/*.py`):
+
+| File | ret sites | param sites | has `from_dict` | calls tomllib/json.loads |
+|------|-----------|-------------|------------------|--------------------------|
+| src/theme_models.py | 2 | 2 | yes | yes |
+| src/context_presets.py | 0 | 3 | no | no |
+| src/log_registry.py | 2 | 1 | yes | yes |
+| src/hot_reloader.py | 1 | 1 | no | no |
+| src/mcp_client.py | 0 | 2 | yes | yes |
+| src/personas.py | 1 | 1 | yes | yes |
+| src/presets.py | 1 | 1 | no | yes |
+| src/tool_presets.py | 1 | 1 | yes | yes |
+| src/type_aliases.py | 1 | 1 | yes | no |
+| src/workspace_manager.py | 1 | 1 | yes | yes |
+| src/events.py | 1 | 0 | no | no |
+| src/gemini_cli_adapter.py | 1 | 0 | no | yes |
+| src/openai_compatible.py | 1 | 0 | no | no |
+| src/paths.py | 1 | 0 | no | yes |
+| src/session_logger.py | 0 | 1 | no | no |
+| src/startup_profiler.py | 1 | 0 | no | no |
+| ... 50 other `src/*.py` | 0 | 0 | (varies) | (varies) |
+
+Totals: **12 `dict[str, Any]` returns + 16 params across 16 files**; ~50 other
+files have zero `dict[str, Any]` in signatures.
+
+Per-file manual classification (the same kind of classification the
+`audit_imports_whitelist.toml` makes for hot-reload files):
+
+- **LEGITIMATE BOUNDARY** (audit must allow): `context_presets.py`
+  (`load_all/save_preset/delete_preset(project_dict: Dict[str, Any])` —
+  `project_dict` IS the wire TOML), `events.py` `to_dict()` (wire
+  serialization for the WS protocol), `openai_compatible.py`
+  `_to_dict_tool_call(tc: ToolCall) -> dict[str, Any]` (converts typed
+  `ToolCall` to vendor wire dict), `theme_models.py` (the schema is the wire
+  for `.ini` rendering), `log_registry.py` (JSON-L log shape), `presets.py`,
+  `tool_presets.py`, `personas.py`, `workspace_manager.py`, `paths.py`,
+  `gemini_cli_adapter.py`, `mcp_client.py` (the MCP wire-protocol parsers),
+  `type_aliases.py` (`from_dict(raw: dict[str, Any])` classmethods — the
+  literal definition of boundary), `session_logger.py` (writes JSONL).
+- **GENUINE VIOLATIONS** (audit should flag, baseline captures them so
+  strict stays green until a migration track fixes): `hot_reloader.py`
+  (`capture_state`/`restore_state(app, ...) -> dict[str, Any]` — internal
+  state, could be a `HotReloadSnapshot` dataclass), `startup_profiler.py`
+  (`snapshot() -> dict[str, Any]` — could be a `ProfilerSnapshot` dataclass).
+
+So the audit must:
+1. Find every `dict[str, Any]` in function signatures (param + return +
+   annotated assignment) in every `src/*.py`.
+2. For each site, check whether its enclosing function is allowlisted in
+   `scripts/boundary_layer_allowlist.toml` (per-file + per-function entries
+   with a `reason` field, mirroring the `audit_imports_whitelist.toml`
+   contract).
+3. Exit 1 in `--strict` mode on any *un*-allowlisted site.
+4. Emit a `WHITELISTED` annotation per allowlisted file so the user sees the
+   audit considered it (mirrors the `audit_imports.py` precedent).
+5. Ship an initial `boundary_layer_allowlist.toml` listing the ~14 legitimate
+   boundary files identified above, each with a `reason` field documenting
+   why it's at the wire.
+
+### Verified `Optional[T]` Return-Type Distribution on master (the blast-radius for GAP-2)
+
+Same AST scan, but counting `Optional[X]` return annotations:
+- **Total `RETURN_OPTIONAL` violations: 3, in 1 file** (`src/history.py`)
+- **Total `PARAM_OPTIONAL` (warning only, never blocks strict): 119 across many files**
+  — these are legal per `error_handling.md` ("argument types that may be
+  `None` describe a caller choice, not a runtime failure").
+
+So widening the audit from 4 files → all `src/*.py` surfaces **3 new strict
+violations** in `src/history.py`. The existing `audit_optional_in_3_files.py`
+already covers the 4 baseline files (all clean). This track adds the 3
+`history.py` sites to a new `audit_optional_returns.baseline.json` so the
+widened strict gate stays green until cruft_elimination Phase 6 (which owns
+those 3 sites) actually migrates them. The 3 sites are documented in the
+allowlist; they are NOT fixed by this track (out of scope; the fix belongs to
+the cruft_elimination Phase 6 Optional[T]-migration work).
+
+## Goals
+
+- **G1.** A working `scripts/audit_boundary_layer.py` that AST-scans all
+  `src/*.py` for `dict[str, Any]` in function signatures (params, returns,
+  annotated locals) and exits 1 in `--strict` mode on any un-allowlisted site.
+
+- **G2.** A working `scripts/boundary_layer_allowlist.toml` that declares the
+  legitimate boundary functions per file, each with a `reason` field, modeled
+  on `audit_imports_whitelist.toml` (with `--show-allowlist` and
+  `--no-allowlist` flags mirroring the imports whitelist precedent).
+
+- **G3.** `audit_optional_in_3_files.py` renamed to
+  `audit_optional_returns.py`, `BASELINE_FILES` replaced with a `src/*.py`
+  glob, docstrings updated to drop the "3 files" fiction. The 3 `history.py`
+  violations baselined in `audit_optional_returns.baseline.json` so strict
+  stays green. Existing strict callers (`code_path_audit_20260607` referenced
+  the old name — update or alias accordingly).
+
+- **G4.** `python.md` §17 enforcement inventory (lines 449-456) corrected to
+  match post-track reality: `audit_boundary_layer.py` implemented, the renamed
+  `audit_optional_returns.py` "scans all `src/*.py`", `audit_imports.py`
+  marked implemented (it already is), and the inventory's "Pre-commit: every
+  commit MUST pass all four audits" line updated to "five audits" (or
+  whatever the actual post-track count is).
+
+- **G5.** `conductor/code_styleguides/error_handling.md` and
+  `conductor/code_styleguides/python.md` references to the renamed script
+  updated (any line saying `audit_optional_in_3_files.py` ->
+  `audit_optional_returns.py`, except the one legacy cross-reference note
+  in `python.md:359` documenting the rename history).
+
+- **G6.** New tests in `tests/test_audit_boundary_layer.py` (≥10 tests:
+  finder detects `dict[str, Any]` in return / param / local annotation;
+  allowlist suppresses findings + emits WHITELISTED; `--strict` exits 1 on
+  un-allowlisted site, exits 0 on allowlisted; `--json` output shape; missing
+  file handling; syntax error handling).
+
+- **G7.** New/updated tests in `tests/test_audit_optional_returns.py`
+  (or update existing test file if one references the old name): ≥5 tests
+  confirming the widened scope, the rename, baseline reading, and
+  `--strict` behavior.
+
+- **G8.** End-of-track report at
+  `docs/reports/TRACK_COMPLETION_enforcement_gap_closure_20260627.md`
+  documenting what shipped + the residual violation baselines + any
+  contradictions from `CONTRADICTIONS_REPORT_20260627.md` closed (C1, C2,
+  C3-partial, C18-partial, C21) and which remain (C5, C6, C16, C17 — those
+  are docs-sync items deferred until tier2 stabilizes, per user directive
+  2026-06-27).
+
+## Functional Requirements
+
+### FR1: `scripts/audit_boundary_layer.py`
+
+- **CLI contract** mirrors `audit_exception_handling.py` + `audit_imports.py`:
+  - `uv run python scripts/audit_boundary_layer.py` — informational (exits 0)
+  - `uv run python scripts/audit_boundary_layer.py --strict` — exits 1 on
+    any un-allowlisted `dict[str, Any]` signature site
+  - `uv run python scripts/audit_boundary_layer.py --json` — JSON output
+  - `uv run python scripts/audit_boundary_layer.py --show-allowlist` —
+    prints the current allowlist + reasons, exits 0
+  - `uv run python scripts/audit_boundary_layer.py --no-allowlist` —
+    audits all sites regardless of allowlist (for one-off audits)
+- **Detection contract** — finds `dict[str, Any]` in:
+  - function return annotations (`def f(...) -> dict[str, Any]`)
+  - function parameter annotations (`def f(x: dict[str, Any])`)
+  - annotated assignments to locals at function scope
+    (`acc: dict[str, dict[str, Any]] = {}` — common pattern in vendor adapters)
+- **Allowlist contract** — reads `scripts/boundary_layer_allowlist.toml`.
+  Per-file entries: `[allowlist."<relative_path>"] reason = "..."`. Within
+  an allowlisted file, ALL `dict[str, Any]` sites are suppressed with a
+  single `WHITELISTED` annotation per file (mirrors `audit_imports.py`
+  precedent; per-line entries would be brittle because the same file has
+  multiple boundary functions). Use `--no-allowlist` to ignore the allowlist.
+- **Coverage:** all `src/*.py`. The audit does NOT traverse `tests/`,
+  `scripts/`, `simulation/` — those aren't subject to §17.7.
+- **Defaults:** informational mode prints a summary table (file, sites,
+  allowlisted?) + a list of violations. `--strict` prints the same and
+  exits 1 if there are un-allowlisted sites.
+- **Source:** 1-space indent, no comments in body, type-hinted, docstrings
+  where the contract is non-obvious. Module docstring explains the §17.7
+  contract + the allowlist pattern.
+
+### FR2: `scripts/boundary_layer_allowlist.toml`
+
+- TOML file modeled on `audit_imports_whitelist.toml`:
+  - Header comment block explaining the purpose + the format.
+  - "Last reviewed: 2026-06-27"
+  - `[allowlist."<relative_path>"]` entries for each legitimate boundary
+    file with a `reason` field documenting why it's at the wire boundary.
+- **Initial contents:** the ~14 legitimate boundary files identified in the
+  Current State Audit (`context_presets.py`, `events.py`,
+  `openai_compatible.py`, `theme_models.py`, `log_registry.py`, `presets.py`,
+  `tool_presets.py`, `personas.py`, `workspace_manager.py`, `paths.py`,
+  `gemini_cli_adapter.py`, `mcp_client.py`, `type_aliases.py`,
+  `session_logger.py`). The two genuine violators (`hot_reloader.py`,
+  `startup_profiler.py`) are NOT in the allowlist — the audit will flag them
+  on master, but `audit_boundary_layer.baseline.json` will record them so
+  `--strict` stays green until a future track migrates them.
+
+### FR3: Rename + widen `audit_optional_in_3_files.py` → `audit_optional_returns.py`
+
+- **Rename:** `git mv scripts/audit_optional_in_3_files.py
+  scripts/audit_optional_returns.py` (preserves git history).
+- **Code changes:**
+  - Module docstring: drop "4 baseline files"; say "all `src/*.py` per
+    §17 post-2026-06-27 widening".
+  - `BASELINE_FILES: tuple[str, ...] = (...)` → `def _discover_src_files() ->
+    list[Path]: return sorted(Path("src").glob("*.py"))` (the precedent is
+    `audit_exception_handling.py`'s glob approach).
+  - `audit_file()` is already generic — no logic change.
+  - Output: the summary line says "scanned N files" with N = the count.
+- **Baseline file:** create `scripts/audit_optional_returns.baseline.json`
+  recording the 3 `src/history.py` `RETURN_OPTIONAL` violations so
+  `--strict` stays green. The strict-mode behavior: exit 1 if findings >
+  baseline, exit 0 otherwise. (Mirrors `audit_weak_types.py`'s baseline +
+  `--strict` contract — see `audit_weak_types.baseline.json`.)
+- **Backward-compat:** The old name `audit_optional_in_3_files.py` is gone.
+  Any external references to the old name must be updated. (Per the
+  pre-flight grep, references exist in `python.md:359`, `python.md:452`,
+  and possibly `error_handling.md` — those are doc edits in G5. The
+  `code_path_audit_20260607` track's plan referenced the old name as a
+  cross-reference contract — that's historical; not updated.)
+
+### FR4: `python.md` §17 enforcement inventory + §17.8 enforcement section
+
+- **§17 inventory table (lines 449-456)** corrected:
+  - Row for `dict[str, Any]` ban: `audit_weak_types.py` (implemented) +
+    `audit_boundary_layer.py --strict` (implemented this track) — BOTH
+    listed, with the boundary audit's note: "uses
+    `scripts/boundary_layer_allowlist.toml`; use `--no-allowlist` to audit
+    all `src/*.py` without suppression."
+  - Row for `Optional[T]` returns: `audit_optional_returns.py` (renamed +
+    widened to all `src/*.py` this track; reads
+    `audit_optional_returns.baseline.json` for the 3 `history.py` residuals
+    until cruft_elimination Phase 6).
+  - Row for local imports + aliasing + repeated `from_dict()`:
+    `audit_imports.py` — marked "✅ implemented" (CORRECTED from current
+    "⚠️ not yet built").
+  - Row for repeated `.from_dict()`: same as above (covered by
+    `audit_imports.py`).
+- **§17.8 enforcement section (lines 357-362)** updated:
+  - Bullet for `audit_optional_returns.py` → reflects rename + widening.
+  - Bullet for `audit_imports.py` → marked implemented (drop the parenthetical
+    "planned in §17.9a").
+  - Bullet for "boundary_layer audit (planned...)" → replaced with bullet
+    for `audit_boundary_layer.py --strict` (implemented, references
+    `boundary_layer_allowlist.toml`).
+  - The "Pre-commit: every commit MUST pass all four audits above" line →
+    "five audits" (weak_types, boundary_layer, optional_returns,
+    exception_handling, imports).
+
+### FR5: Test files
+
+- **`tests/test_audit_boundary_layer.py`** (NEW) — ≥10 tests:
+  - `test_finder_detects_dict_return_annotation` — synthetic .py with a
+    `def f() -> dict[str, Any]: ...` → finding emitted.
+  - `test_finder_detects_dict_param_annotation` — `def f(x: dict[str, Any])`
+    → finding emitted.
+  - `test_finder_detects_dict_local_assignment` — `acc: dict[str, Any] = {}`
+    inside a function → finding emitted.
+  - `test_finder_ignores_non_dict_any` — `def f() -> dict[str, int]` → no
+    finding.
+  - `test_allowlist_suppresses_findings` — file in allowlist → findings
+    suppressed, `WHITELISTED` annotation emitted instead.
+  - `test_strict_exits_1_on_violation` — un-allowlisted violation → exit 1.
+  - `test_strict_exits_0_when_allowlisted` — allowlisted file → exit 0.
+  - `test_json_output_shape` — `--json` output has the expected top-level
+    keys (`files_scanned`, `files_with_findings`, `total_findings`,
+    `by_kind`, `findings`).
+  - `test_missing_file_handling` — referenced file absent → graceful
+    `MISSING_FILE` finding, not a crash.
+  - `test_syntax_error_handling` — malformed .py → graceful `SYNTAX_ERROR`
+    finding, not a crash.
+  - `test_show_allowlist_flag` — `--show-allowlist` prints entries, exits 0.
+- **`tests/test_audit_optional_returns.py`** (NEW) — ≥5 tests:
+  - `test_renamed_script_exists` — `scripts/audit_optional_returns.py`
+    exists; `scripts/audit_optional_in_3_files.py` does NOT.
+  - `test_scans_all_src_files` — audit finds a synthetic `Optional[X]`
+    return in a new file under `src/` that wasn't in the old 4-file
+    baseline. (Use `monkeypatch` to point at a `tmp_path` src/ tree.)
+  - `test_baseline_reading_keeps_strict_green` — with 3 known `history.py`
+    sites baselined, `--strict` exits 0.
+  - `test_strict_exits_1_above_baseline` — add 1 new `Optional[X]` return
+    not in baseline → exit 1.
+  - `test_param_optional_is_warning_not_strict` — `PARAM_OPTIONAL`
+    findings never cause `--strict` to exit 1.
+
+## Non-Functional Requirements
+
+- **1-space indentation** for all Python code (hard rule per workflow.md).
+- **No comments in body** per AGENTS.md "No comments to source code".
+- **CRLF line endings** preserved on Windows (use `manual-slop_edit_file`
+  MCP tool, not native `edit`, to preserve formatting per workflow.md).
+- **Atomic per-task commits** — never batch; one task = one commit + one
+  plan/state update commit.
+- **No diagnostic noise** — no `sys.stderr.write("[FOO] ...")` lines in
+  the audit scripts.
+- **`--json` mode** produces machine-readable output for CI integration.
+- **Default mode** is informational (exit 0) per the precedent of every
+  other audit script; `--strict` is the CI gate.
+- **Performance** — the audit scans all `src/*.py` (~66 files); AST parse
+  + walk should complete in well under 1 second wall-clock (the existing
+  `audit_weak_types.py` does the same scale and is sub-second).
+
+## Architecture Reference
+
+- **`docs/guide_meta_boundary.md`** — the domain-distinction rule; the
+  boundary layer is an Application concept, not a meta-tooling one.
+- **`docs/reports/boundary_layer_20260628.md`** — the *report* this audit
+  *implements*. Lists every legitimate `Metadata` usage and explains why
+  each is at the wire boundary.
+- **`conductor/code_styleguides/python.md` §17.7** — the §17.7 contract:
+  "the ONLY place these patterns are allowed is at the literal wire
+  boundary — the function that calls `tomllib.load()`, `json.loads()`, or
+  a vendor SDK's response parser. The boundary is 2-3 functions per file."
+- **`conductor/code_styleguides/data_oriented_design.md` §8.5** — the
+  Python Type Promotion Mandate (the canonical rule this audit enforces).
+- **`conductor/code_styleguides/error_handling.md`** — the `Optional[T]`
+  ban (and the `Result[T]` + `NIL_T` replacement pattern).
+- **`scripts/audit_imports.py` + `scripts/audit_imports_whitelist.toml`** —
+  the precedent template: AST scan + per-file allowlist + `--strict` CI gate
+  + `--json` / `--show-whitelist` / `--no-whitelist` flags. The new
+  `audit_boundary_layer.py` should match this contract closely.
+- **`scripts/audit_weak_types.py` + `scripts/audit_weak_types.baseline.json`** —
+  the precedent for the `--strict` baseline-JSOא contract (baseline of known
+  violations; `--strict` exits 1 if current findings exceed baseline). The
+  renamed `audit_optional_returns.py` reuses this pattern for the 3
+  `history.py` residuals.
+- **`docs/reports/CONTRADICTIONS_REPORT_20260627.md`** — the source of the
+  contradictions this track closes: C1 (audit name vs behavior), C2
+  (Optional ban scope ambiguity), C3 (audit_imports "planned" but actually
+  built), C18 (2/7 vs actually 4/7 patterns audited), C21 (script name).
+- **`docs/reports/TRACK_COMPLETION_post_module_taxonomy_de_cruft_20260627.md`**
+  — current state of the running parallel track; confirms zero file-overlap.
+
+## Out of Scope
+
+- **Fixing the 3 `src/history.py` `Optional[T]` returns.** Those belong to
+  `cruft_elimination_20260627` Phase 6 (the deferred Optional[T]-returns
+  migration work). This track only *baselines* them so the widened strict
+  gate stays green; the actual migration is the future track's job.
+- **Fixing the 2 `hot_reloader.py` + `startup_profiler.py` `dict[str, Any]`
+  violations.** Same logic: baseline only; a future track migrates them to
+  typed dataclasses (`HotReloadSnapshot`, `ProfilerSnapshot`).
+- **Docs-count drift in `docs/Readme.md`** (providers 5→8, tests 322→251,
+  commands 50+→33). Per user directive 2026-06-27: wait for tier2 branch
+  to stabilize before touching `docs/Readme.md`.
+- **Styleguide §10 Anti-OOP self-contradiction (C16)** and
+  **`type_aliases.md` line 19 table (C17)** — both deferred per user
+  directive (they describe code state that only exists post-merge of the
+  tier2 taxonomy branches; fixing them now would make master's docs
+  describe code master doesn't have).
+- **`RAGChunk.id` field in `guide_rag.md` (C6)** — same branch-sensitivity
+  reason; deferred.
+- **Building the "repeated `.from_dict()` in same expression" enforcement.**
+  `audit_imports.py` already covers it per §17.9c. No new script needed.
+- **Building `scripts/audit_optional_returns.py` baseline migration path.**
+  The 3 `history.py` sites are simply added to the initial baseline JSON;
+  no migration script is needed.
+- **Wire `--strict` mode of `audit_boundary_layer.py` into actual pre-commit
+  hooks in the main repo's `.git/hooks/`.** Per C4 in the contradictions
+  report, pre-commit enforcement is sandbox-only for now; main-repo wiring
+  is a separate track.
+- **Touching any `src/*.py` source.** This track is pure audit +
+  styleguide + tests. Zero `src/` edits.

conductor/tracks/enforcement_gap_closure_20260627/state.toml

@@ -0,0 +1,64 @@
+# Track state for enforcement_gap_closure_20260627
+# Initialized by Tier 1 Orchestrator on 2026-06-27.
+# Implementation delegated to Tier 2 (autonomous) or Tier 3 worker dispatch.
+
+[meta]
+track_id = "enforcement_gap_closure_20260627"
+name = "Enforcement Gap Closure (Boundary-Layer Audit + Optional[T] Audit Widening)"
+status = "active"
+current_phase = 0  # 0 = pre-Phase 1; bump to 1 when implementation starts
+last_updated = "2026-06-27"
+
+[blocked_by]
+# None. This track is parallel-safe against the running
+# tier2/post_module_taxonomy_de_cruft_20260627 branch (zero file overlap
+# verified by Tier 1 against ddcec7b0 + TRACK_COMPLETION file-level changes).
+
+[blocks]
+# None. Follow-up tracks (history.py Optional migration, hot_reloader/
+# startup_profiler dict migration) are documented in metadata.json but not
+# formally tracked here.
+
+[phases]
+# All 4 phases per plan.md. checkpointsha filled when the phase checkpoint
+# commit is made by the implementing Tier 2/Tier 3.
+phase_1 = { status = "pending", checkpointsha = "", name = "Boundary-Layer Audit Script (script + allowlist + 10 tests)" }
+phase_2 = { status = "pending", checkpointsha = "", name = "Optional[T] Audit Rename + Widening (rename + 5 tests + baseline JSON)" }
+phase_3 = { status = "pending", checkpointsha = "", name = "Styleguide Doc Reconciliation (python.md s17 + cross-ref sweep)" }
+phase_4 = { status = "pending", checkpointsha = "", name = "End-of-Track Report + State Update + User Sign-off" }
+
+[tasks]
+# Phase 1: boundary-layer audit script + allowlist + tests
+t1_1 = { status = "pending", commit_sha = "", description = "Write 10 failing tests in tests/test_audit_boundary_layer.py (Red phase)" }
+t1_2 = { status = "pending", commit_sha = "", description = "Implement scripts/audit_boundary_layer.py per spec FR1 (finder + allowlist + strict + json + --show-allowlist + --no-allowlist + --src)" }
+t1_3 = { status = "pending", commit_sha = "", description = "Write scripts/boundary_layer_allowlist.toml with ~14 boundary files + reasons" }
+t1_4 = { status = "pending", commit_sha = "", description = "Run tests/test_audit_boundary_layer.py -v (Green phase); verify all 10 pass" }
+# Phase 2: Optional audit rename + widening
+t2_1 = { status = "pending", commit_sha = "", description = "Write 5 failing tests in tests/test_audit_optional_returns.py (Red phase)" }
+t2_2 = { status = "pending", commit_sha = "", description = "git mv audit_optional_in_3_files.py -> audit_optional_returns.py + widen glob to all src/*.py + add --src flag + create audit_optional_returns.baseline.json with 3 history.py residuals" }
+t2_3 = { status = "pending", commit_sha = "", description = "Run tests/test_audit_optional_returns.py -v (Green phase); verify all 5 pass" }
+# Phase 3: styleguide doc reconciliation
+t3_1 = { status = "pending", commit_sha = "", description = "Edit conductor/code_styleguides/python.md s17 inventory table (lines 449-456) + s17.8 enforcement section (lines 357-362) per spec FR4" }
+t3_2 = { status = "pending", commit_sha = "", description = "Cross-reference sweep for audit_optional_in_3_files.py in conductor/ + docs/ (update enforcement references; preserve historical)" }
+# Phase 4: end-of-track
+t4_1 = { status = "pending", commit_sha = "", description = "Run the 7-audit strict suite (verify all pass; the 2 boundary + 3 Optional residuals baselined)" }
+t4_2 = { status = "pending", commit_sha = "", description = "Write docs/reports/TRACK_COMPLETION_enforcement_gap_closure_20260627.md per spec G8" }
+t4_3 = { status = "pending", commit_sha = "", description = "Update conductor/tracks.md + conductor/chronology.md + state.toml -> status='completed'" }
+t4_4 = { status = "pending", commit_sha = "", description = "Conductor - User Manual Verification (PAUSE for user sign-off)" }
+
+[verification]
+# Filled as phases complete.
+phase_1_complete = false
+phase_2_complete = false
+phase_3_complete = false
+phase_4_complete = false
+all_7_audit_gates_strict_pass = false
+contradictions_closed_c1_c2_c3_partial_c18_partial_c21 = false
+
+[scope_summary]
+# Populated by Tier 1; static scope summary for re-warm after compaction.
+new_files_count = 7
+modified_files_count = 5
+deleted_files_count = 1  # via git mv (audit_optional_in_3_files.py -> audit_optional_returns.py)
+parallel_safe_against_post_module_taxonomy_de_cruft = true
+parallel_safety_evidence = "Tier 1 verified zero file overlap against ddcec7b0 + TRACK_COMPLETION_post_module_taxonomy_de_cruft_20260627.md file-level changes table on 2026-06-27"