# Campaign Plan: metadata_ssdl_defusing_20260624

3-child campaign executed sequentially with budget gates. The umbrella plan is intentionally minimal — each child has its own plan. The umbrella tracks the campaign-wide coordination only.

## Phase 1: Child 1 — Nil Sentinel (metadata_nil_sentinel_20260624)

Focus: Establish the sentinel fallback path. Independent of children 2 and 3.

- [ ] Task 1.1: Tier 2 ships child 1 per its own plan.md.
  - See `conductor/tracks/metadata_nil_sentinel_20260624/plan.md` for the 3-5 tasks.
- [ ] Task 1.2: Run the budget gate.
  - `uv run python -c "..."` to compute the new effective-codepaths number for Metadata.
  - If drop ≥ 10% vs 4.01e22 baseline, proceed to Phase 2.
  - If drop < 10%, PAUSE and report to user.
- [ ] Task 1.3: Re-run the full batched test suite.
  - `uv run python scripts/run_tests_batched.py` → all 11 tiers PASS.
- [ ] Task 1.4: Capture the post-child-1 measurement in `docs/reports/campaign_measurements_20260624.md` (campaign-wide log).

## Phase 2: Child 2 — Generational Handle (metadata_generational_handle_20260624)

Focus: Wrap Metadata in (index, generation). BLOCKED_BY Phase 1 (the sentinel is the generation-mismatch fallback).

- [ ] Task 2.1: Tier 2 ships child 2 per its own plan.md.
- [ ] Task 2.2: Run the budget gate.
  - Re-measure effective-codepaths.
  - If drop ≥ 20% vs post-child-1 measurement, proceed to Phase 3.
  - If drop < 20%, PAUSE and report.
- [ ] Task 2.3: Re-run the full batched test suite.
- [ ] Task 2.4: Append the post-child-2 measurement to the campaign log.

## Phase 3: Child 3 — Field Cache (metadata_field_cache_20260624)

Focus: Add the cache keyed by handle. BLOCKED_BY Phase 2 (the handle provides the stable cache key).

- [ ] Task 3.1: Tier 2 ships child 3 per its own plan.md.
- [ ] Task 3.2: Run the budget gate.
  - Re-measure effective-codepaths.
  - If drop ≥ 30% vs post-child-2 measurement, proceed to Phase 4.
  - If drop < 30%, PAUSE and report.
- [ ] Task 3.3: Re-run the full batched test suite.
- [ ] Task 3.4: Append the post-child-3 measurement to the campaign log.

## Phase 4: End-of-Campaign Report

Focus: Quantify the cumulative effect.

- [ ] Task 4.1: Write `docs/reports/TRACK_COMPLETION_metadata_ssdl_defusing_20260624.md`.
  - 3 measurements (post-child-1, -2, -3) + the 4.01e22 baseline.
  - Total reduction.
  - The 3 SSDL primitives' locations in `src/`.
  - Links to each child's TRACK_COMPLETION.
  - Verdict: did the campaign meet its goal? (Y/N + evidence)
- [ ] Task 4.2: Update this track's `state.toml` to `status = "completed"`, `current_phase = "complete"`, all 4 phases `completed`.
- [ ] Task 4.3: Update `conductor/tracks.md` to add the campaign row + the 3 child rows.

## Budget Gate Quick Reference

| Child | Expected drop | If drop < threshold, PAUSE and report |
|---|---|---|
| 1: Nil Sentinel | ≥ 10% | Pause; investigate why the 6 nil-checks didn't reduce branch count |
| 2: Generational Handle | ≥ 20% | Pause; investigate why lifetime branches didn't collapse |
| 3: Field Cache | ≥ 30% | Pause; investigate why cache lookup didn't reduce branch count |

The thresholds are conservative estimates. Actual drops may be much larger (the heuristic's 4.01e22 is a worst-case upper bound; real numbers may be smaller by orders of magnitude once the techniques are applied).

## Commit Log (Expected, Campaign-Wide)

| Commit | Description |
|---|---|
| (from child 1) | `feat(metadata): NIL_METADATA sentinel + 6 nil-check migrations` |
| (from child 1) | `test(metadata): behavioral test for nil sentinel` |
| (from child 1) | `conductor(state): metadata_nil_sentinel_20260624 SHIPPED` |
| (from child 2) | `feat(metadata): generational handle registry` |
| (from child 2) | `test(metadata): behavioral test for handle lookup` |
| (from child 2) | `conductor(state): metadata_generational_handle_20260624 SHIPPED` |
| (from child 3) | `feat(metadata): MetadataFieldCache keyed by handle` |
| (from child 3) | `test(metadata): behavioral test for cache hit/miss` |
| (from child 3) | `conductor(state): metadata_field_cache_20260624 SHIPPED` |
| (campaign) | `docs(reports): TRACK_COMPLETION for metadata_ssdl_defusing_20260624` |
| (campaign) | `conductor(state): metadata_ssdl_defusing_20260624 SHIPPED` |
| (campaign) | `conductor(tracks): add campaign + 3 child rows` |

Plus per-task plan-update commits per the workflow.

## Verification Commands (run at end of Phase 4)

```bash
# VC1: all 3 children SHIPPED
cat conductor/tracks/metadata_nil_sentinel_20260624/state.toml | grep status
cat conductor/tracks/metadata_generational_handle_20260624/state.toml | grep status
cat conductor/tracks/metadata_field_cache_20260624/state.toml | grep status

# VC2: end-of-campaign report
cat docs/reports/TRACK_COMPLETION_metadata_ssdl_defusing_20260624.md

# VC3: full test suite
uv run python scripts/run_tests_batched.py

# VC4: 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

# VC5: no new top-level src/ files
git diff master..HEAD --stat -- 'src/*.py' | grep -E '\bsrc/[a-z_]+\.py\b' | sort -u

# VC6: behavioral tests
uv run pytest tests/test_metadata_nil_sentinel.py tests/test_metadata_generational_handle.py tests/test_metadata_field_cache.py -v
```