# Directive Hot-Swap Harness Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a directive hot-swap harness that lets the user maintain alternative encodings of the same directive as separate files, compose them into named presets (markdown bills of materials), and hot-swap which preset is active via a single `warm with: <path>` instruction in the role prompt or session message.

**Architecture:** A `conductor/directives/` directory tree where each directive is a subdirectory and each encoding variant is a file (`v1.md`, `v2_<style>.md`). Presets in `conductor/directives/presets/` are markdown files listing which variant files to read. The 5 tier role prompts are updated with a single `warm with: <preset_path>` line that replaces the hardcoded mandatory-reading list. No scripts, no TOML, no build steps — markdown-only, LLM-native.

**Tech Stack:** Markdown files. No code changes. No tests (this is a documentation/tooling track, not a code track). The "test" is: does an LLM follow the `warm with:` instruction and read the listed files?

**Spec:** `docs/superpowers/specs/2026-06-27-directive-hotswap-harness-design.md`

---

## File Structure

### New files (created by this plan)

```
conductor/directives/
  ban_dict_any/v1.md
  ban_any_type/v1.md
  ban_optional_returns/v1.md
  ban_hasattr_dispatch/v1.md
  ban_getattr_dispatch/v1.md
  ban_dict_get_on_known_fields/v1.md
  ban_local_imports/v1.md
  ban_prefix_aliasing/v1.md
  ban_repeated_from_dict/v1.md
  boundary_layer_exception/v1.md
  result_error_pattern/v1.md
  nil_sentinel_pattern/v1.md
  typed_dataclass_fields/v1.md
  metadata_boundary_type/v1.md
  one_space_indent/v1.md
  no_comments_in_body/v1.md
  no_diagnostic_noise/v1.md
  type_hints_required/v1.md
  sdm_dependency_tags/v1.md
  file_naming_convention/v1.md
  no_new_src_files_without_permission/v1.md
  large_files_are_fine/v1.md
  atomic_per_task_commits/v1.md
  tdd_red_green_required/v1.md
  ban_arbitrary_core_mocking/v1.md
  live_gui_poll_not_sleep/v1.md
  batch_verification_not_isolation/v1.md
  git_hard_bans/v1.md
  ban_day_estimates/v1.md
  no_output_filtering/v1.md
  prefer_targeted_tier_runs/v1.md
  mandatory_research_first/v1.md
  no_skip_markers_as_avoidance/v1.md
  deduction_loop_limit/v1.md
  report_instead_of_fix_ban/v1.md
  scope_creep_track_doc_ban/v1.md
  inherited_cruft_ask_first/v1.md
  verbose_commit_message_ban/v1.md
  imgui_scope_verification/v1.md
  modular_controller_pattern/v1.md
  ui_delegation_for_hot_reload/v1.md
  strict_state_management/v1.md
  comprehensive_logging/v1.md
  feature_flag_delete_to_turn_off/v1.md
  rag_six_rules/v1.md
  cache_stable_to_volatile/v1.md
  knowledge_harvest_pattern/v1.md

  presets/
    current_baseline.md
```

### Modified files

```
.opencode/agents/tier1-orchestrator.md          (replace mandatory-reading list with warm with:)
.opencode/agents/tier2-tech-lead.md             (same)
.opencode/agents/tier3-worker.md                (same)
.opencode/agents/tier4-qa.md                    (same)
conductor/tier2/agents/tier2-autonomous.md      (same)
```

### NOT modified (the original docs stay untouched)

```
AGENTS.md                                        (stays as canonical source)
conductor/workflow.md                             (stays as canonical source)
conductor/product-guidelines.md                  (stays as canonical source)
conductor/code_styleguides/*.md                  (all stay as canonical source)
docs/*.md                                         (all stay as canonical source)
```

---

## Phase 1: Directive Harvest

Focus: Systematically comb the doc tree, extract every directive-like statement into a candidate list, resolve granularity (which to merge, split, keep standalone). This is the bulk of the work.

Each task creates one or more `conductor/directives/<name>/v1.md` files. The v1 content is a verbatim lift from the source doc (not a rewrite). The variant header annotates the source location and why this iteration exists.

- [ ] **Step 1.1: Harvest §17 banned patterns (7 directives)**

**Files to read:**
- `conductor/code_styleguides/python.md:243-473` (§17 Banned Patterns — the 7 banned patterns + §17.7 boundary exception + §17.8 enforcement + §17.9 local imports + §17.10 enforcement inventory)

**Directives to create:**

1. `conductor/directives/ban_dict_any/v1.md` — source: `python.md:247-264` (§17.1). Content: the `dict[str, Any]` ban + before/after examples + the boundary exception cross-ref.
2. `conductor/directives/ban_any_type/v1.md` — source: `python.md:266-277` (§17.2). Content: the `Any` ban + before/after.
3. `conductor/directives/ban_optional_returns/v1.md` — source: `python.md:279-299` (§17.3). Content: the `Optional[T]` return ban + the `Result[T]` replacement pattern.
4. `conductor/directives/ban_hasattr_dispatch/v1.md` — source: `python.md:301-326` (§17.4). Content: the `hasattr()` for entity type dispatch ban + the typed Union alternative.
5. `conductor/directives/ban_getattr_dispatch/v1.md` — source: `python.md:328-338` (§17.5). Content: the `getattr(x, 'field', default)` for type dispatch ban.
6. `conductor/directives/ban_dict_get_on_known_fields/v1.md` — source: `python.md:340-350` (§17.6). Content: the `.get('field', default)` on a `dict[str, Any]` ban + direct attribute access alternative.
7. `conductor/directives/boundary_layer_exception/v1.md` — source: `python.md:352-354` (§17.7). Content: the ONE exception — the wire boundary (TOML/JSON parse) where `dict[str, Any]` is allowed.

**Variant header format** (use for ALL v1 files):
```markdown
# <directive_name> — v1

**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §17.N (lines N-M).
This is the baseline encoding — the style currently in production. Future variants
will test alternative encodings (rationale-first, before/after, tabular) against this baseline.

**Source:** `conductor/code_styleguides/python.md:NNN-MMM`

---

<verbatim directive text from the source>
```

- [ ] **Step 1.2: Harvest §17.9 import/aliasing bans (3 directives)**

**Files to read:**
- `conductor/code_styleguides/python.md:364-443` (§17.9 local imports + aliasing + repeated from_dict)

**Directives to create:**

8. `conductor/directives/ban_local_imports/v1.md` — source: `python.md:364-443` (§17.9a). Content: local imports inside functions are banned + the `try/except ImportError` exception + the vendor-SDK-warmup whitelist.
9. `conductor/directives/ban_prefix_aliasing/v1.md` — source: `python.md` (§17.9b, within the 336-409 range). Content: `import X as _X` aliasing-for-naming-convenience is banned.
10. `conductor/directives/ban_repeated_from_dict/v1.md` — source: `python.md` (§17.9c, within the 336-409 range). Content: repeated `.from_dict()` calls in the same expression are banned.

- [ ] **Step 1.3: Harvest error handling conventions (2 directives)**

**Files to read:**
- `conductor/code_styleguides/error_handling.md:22-56` (the 5 patterns) + `error_handling.md:212-264` (hard rules) + `error_handling.md:284-365` (boundary types)

**Directives to create:**

11. `conductor/directives/result_error_pattern/v1.md` — source: `error_handling.md:22-56, 212-242`. Content: the `Result[T]` dataclass pattern (data + errors list, not `Optional[T]` + exceptions). The 5 patterns (nil-sentinel, zero-init, fail-early, AND over OR, error-info as side-channel). The hard rules (`Optional[T]` returns forbidden in baseline files; `Result[T]` for any function that can fail).
12. `conductor/directives/nil_sentinel_pattern/v1.md` — source: `error_handling.md:24-47` (Pattern 1 — Nil-Sentinel Dataclasses). Content: the `NIL_T` singleton pattern replacing `None`. The sentinel type contract.

- [ ] **Step 1.4: Harvest type/data-structure conventions (3 directives)**

**Files to read:**
- `conductor/code_styleguides/data_oriented_design.md:176-215` (§8.5 Python Type Promotion Mandate + §8.6 Boundary Layer + §8.7 C11 framing)
- `conductor/code_styleguides/type_aliases.md:13-87` (the canonical alias set + the extended per-aggregate dataclasses table) + `type_aliases.md:89-160` (Decision Pattern 2.5 — when to promote to its own dataclass) + `type_aliases.md:284-365` (boundary types + anti-patterns)

**Directives to create:**

13. `conductor/directives/typed_dataclass_fields/v1.md` — source: `data_oriented_design.md:176-199` (§8.5). Content: the Python Type Promotion Mandate — use typed `@dataclass(frozen=True, slots=True)` with explicit fields. The 7 banned patterns table.
14. `conductor/directives/metadata_boundary_type/v1.md` — source: `type_aliases.md:40-81` + `data_oriented_design.md:200-215` (§8.6). Content: `Metadata` is the typed fat struct at the wire boundary, NOT `TypeAlias = dict[str, Any]`. The boundary is 2-3 functions per file. When to promote to per-aggregate dataclass vs. when to keep as collapsed codepath.
15. `conductor/directives/boundary_layer_exception/v1.md` — UPDATE the file created in Step 1.1 to also include the `data_oriented_design.md:200-215` (§8.6) and `type_aliases.md` boundary-layer content. This directive cross-references §17.7 (the exception) + §8.6 (the boundary definition) + type_aliases.md (the Metadata-as-boundary-type rule).

- [ ] **Step 1.5: Harvest code style directives (5 directives)**

**Files to read:**
- `conductor/code_styleguides/python.md:7-21` (§1 Indentation + §2 Type Annotations)
- `conductor/code_styleguides/python.md:64-71` (§8 AI-Agent Specific Conventions — no comments, no diagnostic noise)
- `conductor/code_styleguides/python.md:202-211` (§12 SDM)
- `conductor/code_styleguides/python.md:212-224` (§13 Vertical Compaction)
- `conductor/workflow.md:5-20` (Code Style section)

**Directives to create:**

16. `conductor/directives/one_space_indent/v1.md` — source: `python.md:7-20` + `workflow.md:7`. Content: 1-space indentation for ALL Python code. CRLF line endings on Windows. No comments unless explicitly requested.
17. `conductor/directives/no_comments_in_body/v1.md` — source: `python.md:66` + `AGENTS.md:56`. Content: no comments in source code; documentation lives in `/docs`. Only comment on *why* when non-obvious.
18. `conductor/directives/no_diagnostic_noise/v1.md` — source: `python.md:70` + `AGENTS.md` "No Diagnostic Noise in Production" section. Content: no `sys.stderr.write("[XYZ_DIAG] ...")` in production code. Diag goes to log files or temp scripts.
19. `conductor/directives/type_hints_required/v1.md` — source: `python.md:24-31` + `product-guidelines.md:58`. Content: mandatory strict type hints for all parameters, return types, and global variables.
20. `conductor/directives/sdm_dependency_tags/v1.md` — source: `python.md:202-211` (§12) + `product-guidelines.md:59`. Content: Structural Dependency Mapping tags (`[C: ...]`, `[M: ...]`, `[U: ...]`) in docstrings for AI-assisted impact analysis.

- [ ] **Step 1.6: Harvest file/taxonomy conventions (3 directives)**

**Files to read:**
- `AGENTS.md:62-76` (File Size and Naming Convention HARD RULE)
- `conductor/workflow.md:45` (File Naming Convention HARD RULE)
- `conductor/code_styleguides/python.md:234-241` (§15 Modular Controller Pattern)

**Directives to create:**

21. `conductor/directives/file_naming_convention/v1.md` — source: `AGENTS.md:62-76` + `workflow.md:45`. Content: new `src/<thing>.py` files may only be created on the user's explicit request. Helpers go in the parent module. Large files are FINE.
22. `conductor/directives/no_new_src_files_without_permission/v1.md` — source: `AGENTS.md:68-76`. Content: the audit trigger — "is `<thing>` a new system, or is it part of an existing system?" If it's part of an existing system, the file goes in that system's file.
23. `conductor/directives/large_files_are_fine/v1.md` — source: `AGENTS.md:62-67`. Content: large files are FINE. The "small files are good" stance is propaganda from LLM training data. Cognitive load is managed via naming, regions, and navigation tools — NOT via file splitting.

- [ ] **Step 1.7: Harvest process/workflow directives (10 directives)**

**Files to read:**
- `conductor/workflow.md:80-120` (Standard Task Workflow — TDD, atomic commits, delegate)
- `conductor/workflow.md:112-170` (Phase Completion Verification + API Hooks verification)
- `conductor/workflow.md:262-280` (Structural Testing Contract)
- `AGENTS.md:49-85` (Critical Anti-Patterns)
- `AGENTS.md:86-118` (Session-Learned Anti-Patterns)
- `AGENTS.md:119-185` (Process Anti-Patterns)
- `conductor/workflow.md:385-391` (Tier 2 conventions — the 2 new rules)

**Directives to create:**

24. `conductor/directives/atomic_per_task_commits/v1.md` — source: `workflow.md:112` + `AGENTS.md:55`. Content: commit per-task for atomic rollback. Do NOT batch commits.
25. `conductor/directives/tdd_red_green_required/v1.md` — source: `workflow.md:78-100` (Standard Task Workflow steps 4-6). Content: write failing tests before implementing. Run tests, confirm they fail (Red). Implement, run, confirm pass (Green). The Zero-Assertion Ban (tests must have meaningful assertions).
26. `conductor/directives/ban_arbitrary_core_mocking/v1.md` — source: `workflow.md:262`. Content: ban on `unittest.mock.patch` to bypass core infrastructure unless explicitly authorized.
27. `conductor/directives/live_gui_poll_not_sleep/v1.md` — source: `workflow.md:465-475` (Anti-Pattern: push_event + time.sleep + assert). Content: replace `time.sleep(N)` with a poll loop on `get_value` or `wait_for_event`.
28. `conductor/directives/batch_verification_not_isolation/v1.md` — source: `workflow.md:510-514` (Isolated-Pass Verification Fallacy). Content: the only verification that matters for `live_gui` tests is the batch run. Do NOT commit a fix verified only in isolation.
29. `conductor/directives/git_hard_bans/v1.md` — source: `AGENTS.md:59` + `workflow.md:417-430`. Content: `git restore`, `git checkout -- <file>`, `git reset` are FORBIDDEN without explicit user permission. Use `git show` for inspection, not `git checkout`.
30. `conductor/directives/ban_day_estimates/v1.md` — source: `AGENTS.md:60`. Content: no day/hour/minute estimates in track artifacts. Measure effort by scope (N files, M sites, N tasks).
31. `conductor/directives/no_output_filtering/v1.md` — source: `workflow.md:386`. Content: NEVER filter test output through `Select-Object`, `head`, `tail`. Always redirect to a log file.
32. `conductor/directives/prefer_targeted_tier_runs/v1.md` — source: `workflow.md:387`. Content: do NOT run the full 11-tier batch for every verification. Run targeted tiers.
33. `conductor/directives/mandatory_research_first/v1.md` — source: `workflow.md:46`. Content: before reading any file >50 lines, use `get_file_summary`/`py_get_skeleton`/`py_get_code_outline` to map the structure first.

- [ ] **Step 1.8: Harvest process anti-patterns (6 directives)**

**Files to read:**
- `AGENTS.md:119-185` (Process Anti-Patterns — the 8 named patterns)
- `conductor/workflow.md` "Skip-Marker Policy" section

**Directives to create:**

34. `conductor/directives/no_skip_markers_as_avoidance/v1.md` — source: `workflow.md` "Skip-Marker Policy" + `AGENTS.md:54`. Content: `@pytest.mark.skip` is documentation of a known failure, not an escape from fixing the bug. Fix in-session when feasible.
35. `conductor/directives/deduction_loop_limit/v1.md` — source: `AGENTS.md:127` (Process Anti-Pattern #1). Content: at most 2 test runs in a single investigation. After the 2nd failure, STOP and read the code.
36. `conductor/directives/report_instead_of_fix_ban/v1.md` — source: `AGENTS.md:134` (Process Anti-Pattern #2). Content: a 200-line status report is a confession, not a fix. A good status report is 5-10 sentences.
37. `conductor/directives/scope_creep_track_doc_ban/v1.md` — source: `AGENTS.md:143` (Process Anti-Pattern #3). Content: if the user asks for a fix, your output is the fix. A track doc is only for multi-day work.
38. `conductor/directives/inherited_cruft_ask_first/v1.md` — source: `AGENTS.md:149` (Process Anti-Pattern #4). Content: if a file is broken from a previous session, ASK the user before trying to fix it.
39. `conductor/directives/verbose_commit_message_ban/v1.md` — source: `AGENTS.md:176` (Process Anti-Pattern #7). Content: a commit message is 1-3 sentences. If it's longer than 15 lines, it's a report.

- [ ] **Step 1.9: Harvest GUI/architecture directives (5 directives)**

**Files to read:**
- `conductor/product-guidelines.md:29-43` (UX & UI Principles + Code Standards)
- `conductor/workflow.md:39` (ImGui Verification)

**Directives to create:**

40. `conductor/directives/imgui_scope_verification/v1.md` — source: `product-guidelines.md:39` + `workflow.md:39`. Content: all changes to `gui_2.py` MUST be verified using `scripts/check_imgui_scopes.py`. Use `imscope` context managers over manual push/pop.
41. `conductor/directives/modular_controller_pattern/v1.md` — source: `product-guidelines.md:40`. Content: state-independent logic must be moved to module-level functions. Massive `if/elif` dispatch blocks must be refactored into handler maps.
42. `conductor/directives/ui_delegation_for_hot_reload/v1.md` — source: `product-guidelines.md:41`. Content: all complex ImGui rendering logic must be extracted from the `App` class into module-level `render_xxx(app)` functions. The `App` class should only contain thin delegation wrappers.
43. `conductor/directives/strict_state_management/v1.md` — source: `product-guidelines.md:37`. Content: rigorous separation between the Main GUI rendering thread and daemon execution threads. The UI should NEVER hang during AI communication. Use lock-protected queues and events.
44. `conductor/directives/comprehensive_logging/v1.md` — source: `product-guidelines.md:38`. Content: aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs.

- [ ] **Step 1.10: Harvest feature-flag + RAG + cache + knowledge directives (4 directives)**

**Files to read:**
- `conductor/code_styleguides/feature_flags.md`
- `conductor/code_styleguides/rag_integration_discipline.md:11-20` (the 6 rules)
- `conductor/code_styleguides/cache_friendly_context.md:52-74` (the byte-comparison test)
- `conductor/code_styleguides/knowledge_artifacts.md`

**Directives to create:**

45. `conductor/directives/feature_flag_delete_to_turn_off/v1.md` — source: `feature_flags.md`. Content: file presence ("delete to turn off") for side artifacts; config flags for persistent preferences; CLI flags for one-shot overrides.
46. `conductor/directives/rag_six_rules/v1.md` — source: `rag_integration_discipline.md:11-20`. Content: the 6 rules (opt-in, complements, provenance, no mutation, feature-gated, graceful failure).
47. `conductor/directives/cache_stable_to_volatile/v1.md` — source: `cache_friendly_context.md:52-74`. Content: stable-to-volatile context ordering. The byte-comparison test. Layers 1-7 cacheable, 8-12 not.
48. `conductor/directives/knowledge_harvest_pattern/v1.md` — source: `knowledge_artifacts.md`. Content: the category files + provenance + sha256 ledger + digest regeneration pattern.

- [ ] **Step 1.11: Commit the directive harvest**

```bash
git add conductor/directives/
git commit -m "feat(directives): harvest 48 directives from doc tree into conductor/directives/

Systematic extraction of every directive-like statement (imperative,
preference, hard ban, convention, anti-pattern) from the entire doc tree
into conductor/directives/<name>/v1.md files. Each v1 is a verbatim lift
from the source doc with a header annotating the source location.

Sources combed: AGENTS.md, conductor/workflow.md, conductor/product-guidelines.md,
conductor/tech-stack.md, all 10 conductor/code_styleguides/*.md, docs/AGENTS.md.

Original docs remain untouched as canonical source. The conductor/directives/
tree is a parallel structure, not a replacement."
```

---

## Phase 2: Baseline Preset + Role-Prompt Bootstrap

Focus: Create the `current_baseline.md` preset that lists all 48 directives, then create DUPLICATE role prompts (`.bak` files) that use the `warm with:` bootstrap. The original role prompts stay untouched as the fallback path. See the USER DIRECTIVE in spec.md §"The role-prompt bootstrap" (2026-07-02).

> **USER DIRECTIVE (2026-07-02):** Do NOT modify the 5 original `.md` role prompts. Make duplicates with the `.bak` suffix (e.g., `.opencode/agents/tier3-worker.md` becomes a new file `.opencode/agents/tier3-worker.md.bak` — wait, that conflicts with the extension. Use `.warm.md` instead). Update plan steps 2.3-2.7 accordingly: the output files are `.opencode/agents/tier1-orchestrator.warm.md`, `.opencode/agents/tier2-tech-lead.warm.md`, `.opencode/agents/tier3-worker.warm.md`, `.opencode/agents/tier4-qa.warm.md`, `conductor/tier2/agents/tier2-autonomous.warm.md`. The user can `mv <name>.warm.md <name>.md` to promote a duplicate to active, or `rm <name>.warm.md` to fall back.

- [ ] **Step 2.1: Create the baseline preset**

**File:** `conductor/directives/presets/current_baseline.md`

**Content:**

```markdown
# Preset: current_baseline

The baseline directive composition — all v1 variants lifted verbatim from the
current production docs. This is the starting point; alternative presets swap
variants to test different encodings.

## Directives to warm

Read each file below before any action.

- ban_dict_any: conductor/directives/ban_dict_any/v1.md
- ban_any_type: conductor/directives/ban_any_type/v1.md
- ban_optional_returns: conductor/directives/ban_optional_returns/v1.md
- ban_hasattr_dispatch: conductor/directives/ban_hasattr_dispatch/v1.md
- ban_getattr_dispatch: conductor/directives/ban_getattr_dispatch/v1.md
- ban_dict_get_on_known_fields: conductor/directives/ban_dict_get_on_known_fields/v1.md
- boundary_layer_exception: conductor/directives/boundary_layer_exception/v1.md
- ban_local_imports: conductor/directives/ban_local_imports/v1.md
- ban_prefix_aliasing: conductor/directives/ban_prefix_aliasing/v1.md
- ban_repeated_from_dict: conductor/directives/ban_repeated_from_dict/v1.md
- result_error_pattern: conductor/directives/result_error_pattern/v1.md
- nil_sentinel_pattern: conductor/directives/nil_sentinel_pattern/v1.md
- typed_dataclass_fields: conductor/directives/typed_dataclass_fields/v1.md
- metadata_boundary_type: conductor/directives/metadata_boundary_type/v1.md
- one_space_indent: conductor/directives/one_space_indent/v1.md
- no_comments_in_body: conductor/directives/no_comments_in_body/v1.md
- no_diagnostic_noise: conductor/directives/no_diagnostic_noise/v1.md
- type_hints_required: conductor/directives/type_hints_required/v1.md
- sdm_dependency_tags: conductor/directives/sdm_dependency_tags/v1.md
- file_naming_convention: conductor/directives/file_naming_convention/v1.md
- no_new_src_files_without_permission: conductor/directives/no_new_src_files_without_permission/v1.md
- large_files_are_fine: conductor/directives/large_files_are_fine/v1.md
- atomic_per_task_commits: conductor/directives/atomic_per_task_commits/v1.md
- tdd_red_green_required: conductor/directives/tdd_red_green_required/v1.md
- ban_arbitrary_core_mocking: conductor/directives/ban_arbitrary_core_mocking/v1.md
- live_gui_poll_not_sleep: conductor/directives/live_gui_poll_not_sleep/v1.md
- batch_verification_not_isolation: conductor/directives/batch_verification_not_isolation/v1.md
- git_hard_bans: conductor/directives/git_hard_bans/v1.md
- ban_day_estimates: conductor/directives/ban_day_estimates/v1.md
- no_output_filtering: conductor/directives/no_output_filtering/v1.md
- prefer_targeted_tier_runs: conductor/directives/prefer_targeted_tier_runs/v1.md
- mandatory_research_first: conductor/directives/mandatory_research_first/v1.md
- no_skip_markers_as_avoidance: conductor/directives/no_skip_markers_as_avoidance/v1.md
- deduction_loop_limit: conductor/directives/deduction_loop_limit/v1.md
- report_instead_of_fix_ban: conductor/directives/report_instead_of_fix_ban/v1.md
- scope_creep_track_doc_ban: conductor/directives/scope_creep_track_doc_ban/v1.md
- inherited_cruft_ask_first: conductor/directives/inherited_cruft_ask_first/v1.md
- verbose_commit_message_ban: conductor/directives/verbose_commit_message_ban/v1.md
- imgui_scope_verification: conductor/directives/imgui_scope_verification/v1.md
- modular_controller_pattern: conductor/directives/modular_controller_pattern/v1.md
- ui_delegation_for_hot_reload: conductor/directives/ui_delegation_for_hot_reload/v1.md
- strict_state_management: conductor/directives/strict_state_management/v1.md
- comprehensive_logging: conductor/directives/comprehensive_logging/v1.md
- feature_flag_delete_to_turn_off: conductor/directives/feature_flag_delete_to_turn_off/v1.md
- rag_six_rules: conductor/directives/rag_six_rules/v1.md
- cache_stable_to_volatile: conductor/directives/cache_stable_to_volatile/v1.md
- knowledge_harvest_pattern: conductor/directives/knowledge_harvest_pattern/v1.md

## Notes

All v1 (verbatim lifts from current production docs). No alternative encodings
tested yet. This preset is the control group for future experiments.

To create an experimental preset: copy this file, change the variant path for
the directives you want to test (e.g., swap `v1.md` for `v2_rationale_first.md`),
and update the Notes section with your hypothesis.
```

- [ ] **Step 2.2: Commit the preset**

```bash
git add conductor/directives/presets/current_baseline.md
git commit -m "feat(directives): add current_baseline preset (48 directives, all v1)"
```

- [ ] **Step 2.3: Create duplicate `.opencode/agents/tier1-orchestrator.warm.md` (do NOT modify the original)**

**New file:** `.opencode/agents/tier1-orchestrator.warm.md`

**How to create it:** Read the original `.opencode/agents/tier1-orchestrator.md` to get the FULL current content. In the duplicate, find the "MANDATORY: Pre-Action Required Reading" section (or equivalent hardcoded file list). Replace the directive-reading portion with:

```markdown
## MANDATORY: Directive Warm-up

warm with: conductor/directives/presets/current_baseline.md

Read the preset file above. It lists directive variant files to read before any action.
Read each file the preset references. These are your active directives for this session.

If the user specifies a different preset (e.g., "warm with: conductor/directives/presets/exploratory_rationale.md"),
use that instead. The user's instruction overrides the default.
```

**What stays (non-directive reads that remain hardcoded):**
- `AGENTS.md` — project operating rules
- `conductor/workflow.md` — operational workflow
- `conductor/edit_workflow.md` — edit tool contract
- The relevant `docs/guide_*.md` — architecture reference

- [ ] **Step 2.4: Create duplicate `.opencode/agents/tier2-tech-lead.warm.md` (do NOT modify the original)**

**New file:** `.opencode/agents/tier2-tech-lead.warm.md`

Same procedure as Step 2.3 (read original → duplicate → swap directive-reading portion). Non-directive reads that stay hardcoded:
- `AGENTS.md`
- `conductor/workflow.md`
- `conductor/edit_workflow.md`
- `conductor/tier2/githooks/forbidden-files.txt`
- The relevant `docs/guide_*.md`

- [ ] **Step 2.5: Create duplicate `.opencode/agents/tier3-worker.warm.md` (do NOT modify the original)**

**New file:** `.opencode/agents/tier3-worker.warm.md`

Same procedure. Note: Tier 3 may benefit from a reduced preset (fewer directives — they don't need the planning/strategy directives). But for now, use `current_baseline.md` and let the user create a `worker_minimal.md` preset later.

- [ ] **Step 2.6: Create duplicate `.opencode/agents/tier4-qa.warm.md` (do NOT modify the original)**

**New file:** `.opencode/agents/tier4-qa.warm.md`

Same procedure. Tier 4 reads narrowly; the preset can be customized later.

- [ ] **Step 2.7: Create duplicate `conductor/tier2/agents/tier2-autonomous.warm.md` (do NOT modify the original)**

**New file:** `conductor/tier2/agents/tier2-autonomous.warm.md`

Same procedure. This file has the most extensive hardcoded reading list. Replace the directive-reading portion with the `warm with:` bootstrap. The non-directive reads that stay:
- `AGENTS.md`
- `conductor/workflow.md`
- `conductor/edit_workflow.md`
- `conductor/tier2/githooks/forbidden-files.txt`
- `conductor/tracks/tier2_leak_prevention_20260620/spec.md` (this is a track spec, not a directive — stays hardcoded)
- `conductor/tracks/tier2_leak_prevention_20260620/spec.md` (this is a track spec, not a directive — stays hardcoded)

- [ ] **Step 2.8: Commit the role-prompt updates**

```bash
git add .opencode/agents/tier1-orchestrator.md .opencode/agents/tier2-tech-lead.md .opencode/agents/tier3-worker.md .opencode/agents/tier4-qa.md conductor/tier2/agents/tier2-autonomous.md
git commit -m "feat(role-prompts): replace hardcoded directive lists with warm with: bootstrap

All 5 tier role prompts now use 'warm with: conductor/directives/presets/current_baseline.md'
instead of a hardcoded list of ~11 files. The LLM reads the preset, then reads
the variant files it lists. Non-directive reads (AGENTS.md, workflow.md,
edit_workflow.md, forbidden-files.txt, guide_*.md) remain hardcoded.

The user can override the preset per-session by saying 'warm with: <path>' in
their session message. This is the hot-swap mechanism."
```

---

## Phase 3: Verification + End-of-Track

- [ ] **Step 3.1: Verify the directory structure**

```bash
# Count directive directories
ls conductor/directives/ | wc -l

# Count v1.md files
find conductor/directives/ -name "v1.md" | wc -l

# Verify preset exists
test -f conductor/directives/presets/current_baseline.md

# Verify all 5 role prompts have the warm with: line
grep -l "warm with:" .opencode/agents/tier1-orchestrator.md .opencode/agents/tier2-tech-lead.md .opencode/agents/tier3-worker.md .opencode/agents/tier4-qa.md conductor/tier2/agents/tier2-autonomous.md
```

Expected: 48 directive directories, 48 v1.md files, preset exists, 5 role prompts have `warm with:`.

- [ ] **Step 3.2: Manual verification — does the LLM follow the warm with: instruction?**

Start a new OpenCode session with any tier role. Observe whether the LLM:
1. Reads the preset file at `conductor/directives/presets/current_baseline.md`
2. Reads each variant file listed in the preset
3. Has the directives in context for the session

This is the "test" — there's no automated test for this. The signal is: does the LLM behave as if it has read the directives?

- [ ] **Step 3.3: Write end-of-track report**

**File:** `docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md`

Document:
- What shipped (48 directives + baseline preset + 5 role-prompt updates)
- The directory structure
- The preset format
- The `warm with:` bootstrap
- How to hot-swap (create a new preset or tell the LLM "warm with: <path>")
- What's NOT included (no scripts, no TOML, no v2+ variants yet)
- Handoff to future tracks (alternative encoding authoring, Manual Slop integration, token-cost analysis)

- [ ] **Step 3.4: Commit the end-of-track report**

```bash
git add docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md
git commit -m "docs(reports): TRACK_COMPLETION_directive_hotswap_harness_20260627"
```