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/metadata.json

@@ -0,0 +1,68 @@
+{
+  "track_id": "metadata_nil_sentinel_20260624",
+  "name": "Child 1: Metadata Nil Sentinel",
+  "track_type": "campaign_child",
+  "parent_campaign": "metadata_ssdl_defusing_20260624",
+  "created_date": "2026-06-24",
+  "branch": "master",
+  "depends_on": ["code_path_audit_20260607"],
+  "blocks_within_campaign": ["metadata_generational_handle_20260624"],
+  "scope": {
+    "new_files": [
+      "conductor/tracks/metadata_nil_sentinel_20260624/spec.md",
+      "conductor/tracks/metadata_nil_sentinel_20260624/plan.md",
+      "conductor/tracks/metadata_nil_sentinel_20260624/metadata.json",
+      "conductor/tracks/metadata_nil_sentinel_20260624/state.toml",
+      "tests/test_metadata_nil_sentinel.py",
+      "docs/reports/TRACK_COMPLETION_metadata_nil_sentinel_20260624.md"
+    ],
+    "modified_files": [
+      "src/aggregate.py (NIL_METADATA constant + nil-check migrations)",
+      "src/ai_client.py (nil-check migrations; specific files TBD by Tier 2)",
+      "conductor/tracks.md",
+      "docs/reports/campaign_measurements_20260624.md"
+    ],
+    "deleted_files": []
+  },
+  "estimated_effort": {
+    "method": "scope (per workflow.md §Tier 1 Track Initialization Rules). NO day estimates.",
+    "phase_1": "1 task: write the 2 behavioral tests",
+    "phase_2": "1 task: NIL_METADATA constant + 6 nil-check migrations",
+    "phase_3": "1 task: 6 VCs + budget gate + TRACK_COMPLETION + state + tracks.md"
+  },
+  "verification_criteria": [
+    "VC1: NIL_METADATA is defined in src/",
+    "VC2: The 6 nil-check functions no longer have the 3-pattern nil-check",
+    "VC3: Behavioral test exists and passes",
+    "VC4: Budget gate met (drop >= 10% vs 4.01e22 baseline)",
+    "VC5: Full test suite remains green (11/11 tiers PASS)",
+    "VC6: 4 audit gates remain clean"
+  ],
+  "known_issues": [],
+  "deferred_to_followup_tracks": [],
+  "regressions_and_pre_existing_failures": [],
+  "pre_existing_failures_remaining": [],
+  "risk_register": [
+    {
+      "id": "risk-1",
+      "description": "The 6 nil-check functions are in unexpected locations",
+      "likelihood": "low",
+      "impact": "Phase 2 needs to find them via grep + detect_nil_check_pattern",
+      "mitigation": "Audit enumerated all consumer files; detect_nil_check_pattern is the oracle"
+    },
+    {
+      "id": "risk-2",
+      "description": "NIL_METADATA defaults cause downstream bugs",
+      "likelihood": "low",
+      "impact": "Production code that uses the sentinel crashes",
+      "mitigation": "Empty defaults + behavioral test verifies sentinel works in a real call"
+    },
+    {
+      "id": "risk-3",
+      "description": "Budget gate fails (drop < 10%)",
+      "likelihood": "low",
+      "impact": "Child 1 cannot ship; campaign pauses",
+      "mitigation": "The 6 nil-checks are documented; their removal MUST drop the branch count"
+    }
+  ]
+}

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
+```

conductor/tracks/metadata_nil_sentinel_20260624/spec.md

@@ -0,0 +1,98 @@
+# Track Specification: metadata_nil_sentinel_20260624
+
+## Overview
+
+Child 1 of the `metadata_ssdl_defusing_20260624` campaign. Introduces `NIL_METADATA = Metadata(...)` sentinel and migrates the 6 nil-check functions identified by the parent audit. Establishes the fallback path that Child 2 (Generational Handle) returns to on generation mismatch.
+
+## Current State Audit (master @ 7a9261c4)
+
+- `src/aggregate.py` and `src/ai_client.py` contain 6 functions with `is None` / `== None` / `!= None` patterns on `Metadata` (or aliases of `dict[str, Any]`). These are detected by `src/code_path_audit_ssdl.detect_nil_check_pattern`.
+- The parent audit (`docs/reports/code_path_audit/2026-06-22/AUDIT_REPORT.md` Finding 1) reports "6 nil-check functions" and "4.01e22 effective codepaths" for the `Metadata` aggregate.
+- No `NIL_METADATA` constant exists.
+
+## Goals
+
+| ID | Goal | Acceptance |
+|---|---|---|
+| G1 | `NIL_METADATA = Metadata(...)` constant exists in the production source | `grep -rn "NIL_METADATA" src/` finds the constant + the 6 migration sites |
+| G2 | The 6 nil-check functions use the sentinel | `src.code_path_audit_ssdl.detect_nil_check_pattern` returns 0 for the 6 functions after migration |
+| G3 | 1 behavioral test for the sentinel | `tests/test_metadata_nil_sentinel.py` exists; all assertions pass |
+| G4 | Budget gate met: effective-codepaths drop ≥ 10% vs 4.01e22 baseline | `compute_effective_codepaths(Metadata_profile)` returns a number ≥ 10% smaller than 4.01e22 |
+
+## Non-Goals
+
+- Touching the 4 other `dict[str, Any]` aliases (FileItem, CommsLogEntry, HistoryMessage, ToolDefinition, ToolCall) — they have similar patterns (parent audit Finding 2) but are out of scope for this child
+- Touching the list-typed aggregates (CommsLog, History, FileItems) — out of scope
+- Touching the 3 candidate aggregates (ToolSpec, ChatMessage, ProviderHistory) — blocked on `any_type_componentization_20260621` (NOT on master)
+- Refactoring the 6 functions beyond the nil-check migration (the change is surgical: replace the nil-check with sentinel-return)
+- Adding new audit infrastructure (the campaign USES the existing SSDL functions)
+
+## Functional Requirements
+
+### FR1: Define `NIL_METADATA`
+
+In a sensible location (likely `src/aggregate.py` since it's the Metadata parent module per `src/code_path_audit.py:343-368`'s `CANONICAL_MEMORY_DIM`), add:
+
+```python
+NIL_METADATA: Metadata = Metadata(
+    # safe defaults; the exact contents are up to Tier 2
+)
+```
+
+The defaults MUST be safe (no-op / no-value) such that consumers can blindly use `entry or NIL_METADATA` without triggering KeyError or AttributeError.
+
+### FR2: Migrate the 6 nil-check functions
+
+For each of the 6 functions detected by `src/code_path_audit_ssdl.detect_nil_check_pattern`:
+- Replace `if entry is None: ...` / `if entry is None or entry == "": ...` / `if entry != None: ...` patterns with sentinel-return
+- The most common pattern: `entry = entry or NIL_METADATA` at the top of the function
+- Preserve the function's existing behavior for non-nil cases
+
+### FR3: Behavioral test
+
+`tests/test_metadata_nil_sentinel.py` with at least 2 tests:
+- `test_nil_metadata_is_defined`: assert `NIL_METADATA` exists and is a valid `Metadata` (or `dict[str, Any]` if Metadata is a TypeAlias)
+- `test_migrated_function_uses_sentinel`: call one of the 6 migrated functions with `None` and assert it returns the sentinel (or behavior equivalent to using the sentinel)
+
+## Non-Functional Requirements
+
+- NFR1: 1-space indentation
+- NFR2: CRLF line endings on Windows
+- NFR3: No comments in source code
+- NFR4: Per-task atomic commits with git notes
+- NFR5: No new pip dependencies
+- NFR6: The 6 migration sites use the existing convention (sentinel pattern, not new abstractions)
+- NFR7: No new `src/<thing>.py` files (per AGENTS.md) — `NIL_METADATA` lives in `src/aggregate.py` or another existing module
+
+## Architecture Reference
+
+- `src/code_path_audit_ssdl.py:84-100` — `detect_nil_check_pattern` (the function that identifies the 6 sites)
+- `src/code_path_audit.py:343-368` — `CANONICAL_MEMORY_DIM` (where Metadata's canonical location is)
+- `src/aggregate.py` — the parent module for `Metadata`
+- `docs/reports/code_path_audit/2026-06-22/AUDIT_REPORT.md` Finding 1 — the 6 nil-check functions and the proposed fix
+- `conductor/code_styleguides/data_oriented_design.md` — the canonical DOD reference
+
+## Out of Scope
+
+- All other aggregates (deferred to a follow-up campaign)
+- The 3 candidate aggregates (blocked on `any_type_componentization_20260621`)
+- Runtime profiling (Track F from the previous menu; deferred)
+
+## Verification Criteria (Definition of Done)
+
+| # | Criterion | Verification command |
+|---|---|---|
+| VC1 | `NIL_METADATA` is defined in `src/` | `grep -rn "NIL_METADATA" src/` returns ≥ 1 hit |
+| VC2 | The 6 nil-check functions no longer have the 3-pattern nil-check | `src/code_path_audit_ssdl.detect_nil_check_pattern` returns False for all 6 |
+| VC3 | Behavioral test exists and passes | `uv run pytest tests/test_metadata_nil_sentinel.py -v` |
+| VC4 | Budget gate met | `compute_effective_codepaths(Metadata_profile)` returns number ≥ 10% smaller than 4.01e22 |
+| VC5 | Full test suite remains green | `uv run python scripts/run_tests_batched.py` → 11/11 tiers PASS |
+| VC6 | 4 audit gates remain clean | weak_types ≤ 112, type_registry in sync, main_thread_imports clean, no_models_config_io clean |
+
+## Risks
+
+| # | Risk | Likelihood | Mitigation |
+|---|---|---|---|
+| R1 | The 6 nil-check functions are in unexpected locations (not aggregate.py or ai_client.py) | low | `detect_nil_check_pattern` enumerates all consumer files; the audit identified them |
+| R2 | The `NIL_METADATA` defaults are wrong (cause downstream bugs) | low | The defaults should be safe (empty Metadata with no required fields). Behavioral test verifies sentinel works in a real call. |
+| R3 | Budget gate fails (drop < 10%) | low | The 6 nil-checks are documented; their removal MUST drop. If not, the SSDL math is wrong (separate investigation). |

conductor/tracks/metadata_nil_sentinel_20260624/state.toml

@@ -0,0 +1,43 @@
+# Track state for metadata_nil_sentinel_20260624
+# Child 1 of metadata_ssdl_defusing_20260624 campaign.
+# 3 phases, 3 tasks. Tier 2 to execute per conductor/workflow.md.
+
+[meta]
+track_id = "metadata_nil_sentinel_20260624"
+name = "Child 1: Metadata Nil Sentinel"
+status = "active"
+current_phase = 0
+last_updated = "2026-06-24"
+
+[parent]
+parent_campaign = "metadata_ssdl_defusing_20260624"
+
+[blocked_by]
+code_path_audit_20260607 = "shipped"
+
+[blocks]
+# Within the campaign:
+metadata_generational_handle_20260624 = "pending child 1"
+
+[phases]
+phase_1 = { status = "pending", checkpointsha = "", name = "Behavioral Test" }
+phase_2 = { status = "pending", checkpointsha = "", name = "Implementation (NIL_METADATA + 6 migrations)" }
+phase_3 = { status = "pending", checkpointsha = "", name = "Verification + Budget Gate" }
+
+[tasks]
+t1_1 = { status = "pending", commit_sha = "", description = "Write tests/test_metadata_nil_sentinel.py with 2 tests (red)" }
+t2_1 = { status = "pending", commit_sha = "", description = "Add NIL_METADATA constant + migrate 6 nil-check functions" }
+t3_1 = { status = "pending", commit_sha = "", description = "Run all 6 VCs; capture budget gate measurement; write TRACK_COMPLETION; update state + tracks.md" }
+
+[verification]
+vc1_nil_metadata_defined = false
+vc2_6_nil_checks_migrated = false
+vc3_behavioral_test_passes = false
+vc4_budget_gate_met = false
+vc5_full_test_suite_green = false
+vc6_audit_gates_clean = false
+
+[budget_gate]
+baseline = 4.01e+22
+expected_drop_pct = 10
+post_child_1_measurement = null