conductor(campaign): metadata_ssdl_defusing_20260624 - 3-child SSDL defusing campaign

Campaign: address the parent code_path_audit_20260607 Finding 1 (CRITICAL)
Metadata 4.01e22 effective codepaths via 3 SSDL techniques.

3 children, sequential, with budget gates:
1. metadata_nil_sentinel_20260624 (>= 10% drop): introduce
   NIL_METADATA sentinel + migrate 6 nil-check functions.
2. metadata_generational_handle_20260624 (>= 20% drop,
   BLOCKED_BY 1): wrap Metadata in (index, generation) handle;
   collapse lifetime branches to 1 lookup + 1 cmp.
3. metadata_field_cache_20260624 (>= 30% drop, BLOCKED_BY 2):
   MetadataFieldCache keyed by (handle.index, field_name);
   123 string-keyed entry.get('key', default) sites become
   cache lookups.

Each child has its own spec/plan/metadata/state. Budget gate
after each child: re-measure effective codepaths; if drop < threshold,
PAUSE the campaign and report to user.

End-of-campaign TRACK_COMPLETION captures the cumulative reduction
vs the 4.01e22 baseline. Deferred follow-up: apply the same
3 SSDL primitives to the 4 other dict[str, Any] aliases
(FileItem, CommsLogEntry, HistoryMessage, ToolDefinition, ToolCall).

16 files committed: 4 directories x 4 files each (spec, plan,
metadata, state).

conductor/tracks/metadata_nil_sentinel_20260624/plan.md

@@ -0,0 +1,92 @@
+# Plan: metadata_nil_sentinel_20260624
+
+3 tasks, 3 atomic commits. TDD: write the test first (red), implement (green), commit.
+
+## Phase 1: Behavioral Test (1 task)
+
+Focus: Write the failing test for the sentinel.
+
+- [ ] Task 1.1: Write `tests/test_metadata_nil_sentinel.py`.
+  - WHERE: New file `tests/test_metadata_nil_sentinel.py`
+  - WHAT: 2 tests:
+    - `test_nil_metadata_is_defined`: `from src.aggregate import NIL_METADATA; assert NIL_METADATA is not None; assert isinstance(NIL_METADATA, dict) or isinstance(NIL_METADATA, Metadata)` (depending on whether Metadata is a TypeAlias or class)
+    - `test_detect_nil_check_pattern_returns_false_for_migrated_functions`: import the 6 migrated functions; assert `detect_nil_check_pattern` returns False for each
+  - HOW: Use the existing `src/code_path_audit_ssdl.detect_nil_check_pattern` as the oracle. Use 1-space indentation.
+  - SAFETY: The test file imports the 6 functions. Identify them by running `grep` for `is None` patterns in `src/aggregate.py` and `src/ai_client.py`. If Tier 2 finds additional functions in other files, include them too.
+  - COMMIT: `test(metadata): behavioral test for nil sentinel (NIL_METADATA)`
+  - GIT NOTE: 2 tests, imports the 6 functions, asserts detect_nil_check_pattern returns False for each; will be RED until Phase 2 ships
+  - VERIFY: `uv run pytest tests/test_metadata_nil_sentinel.py -v` shows 2/2 FAIL (expected; the sentinel doesn't exist yet)
+
+## Phase 2: Implementation (1 task)
+
+Focus: Define `NIL_METADATA` and migrate the 6 functions.
+
+- [ ] Task 2.1: Add `NIL_METADATA` and migrate the 6 nil-check functions.
+  - WHERE: `src/aggregate.py` (NIL_METADATA constant) + the 6 files containing the nil-check functions (likely `src/aggregate.py` and `src/ai_client.py`)
+  - WHAT:
+    - Add `NIL_METADATA: Metadata = Metadata(...)` constant in `src/aggregate.py` (the defaults are safe; an empty `{}` if Metadata is a TypeAlias)
+    - For each of the 6 nil-check functions, replace the `if entry is None: ...` / `if entry == None: ...` / `if entry != None: ...` pattern with sentinel-return
+    - The most common pattern: `entry = entry or NIL_METADATA` at the top of the function (replaces the `if entry is None: return default` early-return)
+  - HOW: Use `manual-slop_edit_file` for each migration site. Use `manual-slop_py_add_def` for the `NIL_METADATA` constant.
+  - SAFETY:
+    - Verify with `ast.parse(open("src/aggregate.py").read())`
+    - Run `uv run pytest tests/test_metadata_nil_sentinel.py -v` → 2/2 PASS
+    - Run the 14 previously-failing tests from `fix_test_failures_20260624` → 14/14 PASS (no regression)
+  - COMMIT: `feat(metadata): NIL_METADATA sentinel + 6 nil-check migrations`
+  - GIT NOTE: 6 functions refactored to use sentinel-return; established the fallback that child 2's generation-mismatch path returns to
+  - VERIFY: `uv run pytest tests/test_metadata_nil_sentinel.py -v` shows 2/2 PASS
+
+## Phase 3: Verification + Budget Gate (1 task)
+
+Focus: Run all 6 VCs + the budget gate.
+
+- [ ] Task 3.1: Run all 6 VCs; capture the budget gate measurement.
+  - WHERE: All audit gates + test suite + SSDL measurement
+  - WHAT:
+    - Run VC1-VC6 (the 6 verification criteria from the spec)
+    - Compute the new effective-codepaths number: `uv run python -c "from src.code_path_audit_ssdl import compute_effective_codepaths; from src.code_path_audit import AggregateProfile, ...; profile = ...; print(compute_effective_codepaths(profile, 'src'))"`
+    - Compute the drop vs 4.01e22 baseline; if drop ≥ 10%, mark the budget gate as PASS
+    - Write the child's TRACK_COMPLETION report at `docs/reports/TRACK_COMPLETION_metadata_nil_sentinel_20260624.md`
+    - Update this track's `state.toml` to `status = "completed"`, `current_phase = "complete"`, all 3 phases `completed`
+    - Append the post-child-1 measurement to `docs/reports/campaign_measurements_20260624.md` (the campaign-level log)
+    - Update `conductor/tracks.md` to add a row for this child
+  - HOW: Run each VC command, capture output, write the report.
+  - SAFETY: The 2 pre-existing-violation audit gates (NG1, NG2 from `code_path_audit_polish_20260622`) are still out of scope. Do not regress them.
+  - COMMIT: 3 commits: `conductor(state): metadata_nil_sentinel_20260624 SHIPPED`, `docs(reports): TRACK_COMPLETION for metadata_nil_sentinel_20260624`, `conductor(tracks): add metadata_nil_sentinel_20260624 row`
+  - GIT NOTE: 1 per commit per workflow.md
+  - VERIFY: All 6 VCs pass; budget gate met (drop ≥ 10%); campaign unblocked for child 2
+
+## Commit Log (Expected)
+
+1. `test(metadata): behavioral test for nil sentinel (NIL_METADATA)` (Task 1.1)
+2. `feat(metadata): NIL_METADATA sentinel + 6 nil-check migrations` (Task 2.1)
+3. `conductor(state): metadata_nil_sentinel_20260624 SHIPPED` (Task 3.1)
+4. `docs(reports): TRACK_COMPLETION for metadata_nil_sentinel_20260624` (Task 3.1)
+5. `conductor(tracks): add metadata_nil_sentinel_20260624 row` (Task 3.1)
+
+Plus per-task plan-update commits per the workflow.
+
+## Verification Commands (run at end of Phase 3)
+
+```bash
+# VC1: NIL_METADATA defined
+grep -rn "NIL_METADATA" src/
+
+# VC2: detect_nil_check_pattern returns False for the 6 functions
+uv run python -c "from src.code_path_audit_ssdl import detect_nil_check_pattern; from src.code_path_audit import FunctionRef; ...; [assert not detect_nil_check_pattern(f, 'src') for f in the_6_functions]"
+
+# VC3: behavioral test
+uv run pytest tests/test_metadata_nil_sentinel.py -v
+
+# VC4: budget gate (measure and compare)
+uv run python -c "from src.code_path_audit_ssdl import compute_effective_codepaths; ...; print(compute_effective_codepaths(metadata_profile, 'src'))"
+
+# VC5: full test suite
+uv run python scripts/run_tests_batched.py
+
+# VC6: 4 audit gates
+uv run python scripts/audit_weak_types.py --strict
+uv run python scripts/generate_type_registry.py --check
+uv run python scripts/audit_main_thread_imports.py
+uv run python scripts/audit_no_models_config_io.py
+```