Private
Public Access
0
0

docs(reports): TRACK_COMPLETION_directive_hotswap_harness_20260627

This commit is contained in:
2026-07-02 23:27:25 -04:00
parent bbbfbd3947
commit c9f30abffc
2 changed files with 271 additions and 21 deletions
@@ -2,12 +2,13 @@
# Initialized by Tier 1 Orchestrator on 2026-06-27.
# Implementation delegated to Tier 2 (autonomous) or Tier 3 worker dispatch.
# This is Track 1 of Campaign A (Directive Encoding Campaign).
# Phase 2 + Phase 3 completed 2026-07-02 (manual verification §3.2 deferred to user).
[meta]
track_id = "directive_hotswap_harness_20260627"
name = "Directive Hot-Swap Harness (OpenCode Directive Presets)"
status = "active"
current_phase = 2
current_phase = 3
last_updated = "2026-07-02"
[blocked_by]
@@ -19,9 +20,9 @@ directive_encoding_experiments = "planned (future; v2+ variant authoring)"
manual_slop_directive_lab = "planned (future; GUI integration)"
[phases]
phase_1 = { status = "completed", checkpointsha = "ce0564fe", name = "Directive Harvest (10 steps: 48 directives from doc tree into conductor/directives/)" }
phase_2 = { status = "in_progress", checkpointsha = "", name = "Baseline Preset + Role-Prompt Bootstrap (8 steps: preset + 5 role-prompt warm with: updates)" }
phase_3 = { status = "pending", checkpointsha = "", name = "Verification + End-of-Track (4 steps: dir structure verify + manual LLM verify + report + commit)" }
phase_1 = { status = "completed", checkpointsha = "ce0564fe", name = "Directive Harvest (10 steps: 51 directives from doc tree into conductor/directives/)" }
phase_2 = { status = "completed", checkpointsha = "6ba4bdd", name = "Baseline Preset + Role-Prompt Bootstrap (8 steps: preset + 5 role-prompt warm with: updates)" }
phase_3 = { status = "in_progress", checkpointsha = "", name = "Verification + End-of-Track (4 steps: dir structure verify + manual LLM verify + report + commit)" }
[tasks]
# Phase 1: directive harvest
@@ -37,31 +38,33 @@ t1_9 = { status = "completed", commit_sha = "fa3e5381", description = "Harvest G
t1_10 = { status = "completed", commit_sha = "cdc0f140", description = "Harvest feature-flag + RAG + cache + knowledge directives + 4 new styleguides (8 directives: feature_flag_delete_to_turn_off, rag_six_rules, cache_stable_to_volatile, knowledge_harvest_pattern, config_state_owner, workspace_paths, test_sandbox, chroma_cache_path). Skipped code_path_audit.md (descriptive)." }
t1_11 = { status = "completed", commit_sha = "ce0564fe", description = "Commit the directive harvest summary (51 v1.md files; +1 meta-summary HARVEST_SUMMARY.md)" }
# Phase 2: baseline preset + role-prompt bootstrap
t2_1 = { status = "pending", commit_sha = "", description = "Create conductor/directives/presets/current_baseline.md (48 directives listed)" }
t2_2 = { status = "pending", commit_sha = "", description = "Commit the baseline preset" }
t2_3 = { status = "pending", commit_sha = "", description = "Update .opencode/agents/tier1-orchestrator.md with warm with: bootstrap" }
t2_4 = { status = "pending", commit_sha = "", description = "Update .opencode/agents/tier2-tech-lead.md with warm with: bootstrap" }
t2_5 = { status = "pending", commit_sha = "", description = "Update .opencode/agents/tier3-worker.md with warm with: bootstrap" }
t2_6 = { status = "pending", commit_sha = "", description = "Update .opencode/agents/tier4-qa.md with warm with: bootstrap" }
t2_7 = { status = "pending", commit_sha = "", description = "Update conductor/tier2/agents/tier2-autonomous.md with warm with: bootstrap" }
t2_8 = { status = "pending", commit_sha = "", description = "Commit the 5 role-prompt updates" }
t2_1 = { status = "completed", commit_sha = "2ddaeb52", description = "Create conductor/directives/presets/current_baseline.md (51 directives listed; not the 48 in the plan)" }
t2_2 = { status = "completed", commit_sha = "2ddaeb52", description = "Commit the baseline preset (combined with t2_1 in a single atomic commit; commit includes 1-line state.toml scope drift setting phase_2 to in_progress)" }
t2_3 = { status = "completed", commit_sha = "35831084", description = "Create .opencode/agents/tier1-orchestrator.warm.md duplicate with warm with: bootstrap (Session Start Checklist items 6-9 replaced)" }
t2_4 = { status = "completed", commit_sha = "b082cb15", description = "Create .opencode/agents/tier2-tech-lead.warm.md duplicate with warm with: bootstrap (TWO sections: CRITICAL: Read the canonical docs FIRST + Session Start Checklist; items 6-9 replaced in both)" }
t2_5 = { status = "completed", commit_sha = "40764252", description = "Create .opencode/agents/tier3-worker.warm.md duplicate with warm with: bootstrap (Task Start Checklist items 2-3 replaced)" }
t2_6 = { status = "completed", commit_sha = "b2aebbc9", description = "Create .opencode/agents/tier4-qa.warm.md duplicate with warm with: bootstrap (Context Amnesia 'must read' sentence replaced)" }
t2_7 = { status = "completed", commit_sha = "7b0d1164", description = "Create conductor/tier2/agents/tier2-autonomous.warm.md duplicate with warm with: bootstrap (Pre-Action Required Reading items 7-10 replaced)" }
t2_8 = { status = "completed", commit_sha = "6ba4bdd", description = "Combined summary meta-commit (empty -- all 5 .warm.md files were committed atomically in t2_3..t2_7)" }
# Phase 3: verification + end-of-track
t3_1 = { status = "pending", commit_sha = "", description = "Verify directory structure (48 dirs, 48 v1.md files, preset exists, 5 role prompts have warm with:)" }
t3_2 = { status = "pending", commit_sha = "", description = "Manual verification: does the LLM follow the warm with: instruction?" }
t3_3 = { status = "pending", commit_sha = "", description = "Write docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md" }
t3_4 = { status = "pending", commit_sha = "", description = "Commit the end-of-track report" }
t3_1 = { status = "completed", commit_sha = "bbbfbd39", description = "Verify directory structure (53 entries, 51 v1.md files, preset exists, 5 .warm.md role-prompt duplicates exist, 5 originals untouched) -- all 5 criteria PASS" }
t3_2 = { status = "deferred", commit_sha = "", description = "Manual verification: does the LLM follow the warm with: instruction? DEFERRED to user per directive (requires live OpenCode session)" }
t3_3 = { status = "completed", commit_sha = "PENDING", description = "Write docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md" }
t3_4 = { status = "in_progress", commit_sha = "PENDING", description = "Commit the end-of-track report + this state.toml update atomically" }
[verification]
phase_1_complete = true
phase_2_complete = false
phase_3_complete = false
phase_2_complete = true
phase_3_complete = true # §3.1 + §3.3 + §3.4 done; §3.2 deferred to user
directive_count = 51
preset_exists = false
role_prompts_updated = false
preset_exists = true
role_prompts_updated = true # the 5 .warm.md duplicates exist; originals are intact as rollback
end_of_track_report_exists = true
manual_verification_deferred = true # §3.2 deferred to user
[campaign_context]
campaign_name = "Directive Encoding Campaign (Campaign A)"
track_1 = "directive_hotswap_harness_20260627 (THIS; harvest + scaffold + baseline preset + role-prompt bootstrap)"
track_1 = "directive_hotswap_harness_20260627 (THIS; harvest + scaffold + baseline preset + role-prompt bootstrap) — Phase 3 complete (excluding §3.2 deferred)"
track_2 = "directive_encoding_experiments (future; v2+ variant authoring + preset experimentation)"
track_3 = "manual_slop_directive_lab (future; GUI integration)"
sibling_campaign = "Video Analysis Campaign 2 (Campaign B; 4 new videos; separate track)"
@@ -0,0 +1,247 @@
# Track Completion: directive_hotswap_harness_20260627
**Date:** 2026-07-02
**Track ID:** `directive_hotswap_harness_20260627`
**Track Name:** Directive Hot-Swap Harness (OpenCode Directive Presets)
**Campaign:** A (Directive Encoding Campaign) — Track A-1
**Status:** COMPLETE (with §3.2 manual verification deferred to user)
---
## What Shipped
### Phase 1 (already complete before this report)
48+ directives harvested from the doc tree into `conductor/directives/<name>/v1.md` files. Final count: **51 v1.md files** (4 more than the plan's claimed 48 due to the 2026-07-02 spec expansion of Step 1.10 to cover 5 additional styleguides; `code_path_audit.md` was skipped as descriptive-only).
### Phase 2 (this report's scope)
1. **`conductor/directives/presets/current_baseline.md`** — the baseline preset, a markdown bill of materials listing all 51 directives alphabetically with paths. Used as the default `warm with:` target.
2. **5 `.warm.md` role-prompt duplicates**`.opencode/agents/{tier1-orchestrator, tier2-tech-lead, tier3-worker, tier4-qa}.warm.md` and `conductor/tier2/agents/tier2-autonomous.warm.md`. Each is a byte-identical-to-original copy of the corresponding `.md` role prompt, with the directive-reading portion replaced by a `warm with: conductor/directives/presets/current_baseline.md` bootstrap block.
3. **5 ORIGINAL `.md` role prompts** — UNTOUCHED. They serve as the rollback target. Verified via `git diff e13d8b9b..HEAD --` showing zero changes to:
- `.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`
### Phase 3 (this report's scope)
4. **Verification report** at `docs/reports/phase3_verification_directive_hotswap_harness_20260627.md` documenting all 5 verification criteria PASSED.
---
## Directory Structure (as shipped)
```
conductor/directives/ # 53 entries
├── atomic_per_task_commits/v1.md # 51 directive directories (each with v1.md)
├── ban_any_type/v1.md
├── ... (48 more) ...
├── workspace_paths/v1.md
├── presets/ # the preset directory
│ └── current_baseline.md # the baseline preset (51 entries)
└── HARVEST_SUMMARY.md # the harvest meta-summary (Phase 1 artifact)
.opencode/agents/ # 4 + 5 files
├── tier1-orchestrator.md # ORIGINAL (untouched)
├── tier1-orchestrator.warm.md # NEW DUPLICATE (warm-with: bootstrap)
├── tier2-tech-lead.md # ORIGINAL (untouched)
├── tier2-tech-lead.warm.md # NEW DUPLICATE (warm-with: bootstrap)
├── tier3-worker.md # ORIGINAL (untouched)
├── tier3-worker.warm.md # NEW DUPLICATE (warm-with: bootstrap)
├── tier4-qa.md # ORIGINAL (untouched)
├── tier4-qa.warm.md # NEW DUPLICATE (warm-with: bootstrap)
├── explore.md
└── general.md
conductor/tier2/agents/ # 1 + 1 files
├── tier2-autonomous.md # ORIGINAL (untouched)
└── tier2-autonomous.warm.md # NEW DUPLICATE (warm-with: bootstrap)
```
---
## The `.warm.md` Convention (How to Promote / Fall Back)
The `.warm.md` files are duplicates with a single change: the directive-reading portion of the pre-action reading list is replaced with a `warm with:` bootstrap. The originals are untouched so the user has a rollback path.
### To promote a `.warm.md` to active
```bash
mv .opencode/agents/tier3-worker.warm.md .opencode/agents/tier3-worker.md
```
This replaces the original (which is the fallback target). Note: this is destructive of the original; if you want to keep the original, make a `.bak` first.
### To fall back from a `.warm.md` to the original
```bash
rm .opencode/agents/tier3-worker.warm.md
```
The original `.opencode/agents/tier3-worker.md` is still there (untouched) and will be used.
### To override the preset per-session
The user can say `warm with: <path>` in their session message, e.g.:
```
warm with: conductor/directives/presets/exploratory_rationale.md
```
This hot-swaps which preset the LLM warms up with, without any file edits. The new preset must exist; if it doesn't, the LLM falls back to the default (`current_baseline.md`).
### To create an experimental preset
1. Copy `conductor/directives/presets/current_baseline.md` to a new file.
2. Change the variant path for the directives you want to test (e.g., swap `v1.md` for `v2_rationale_first.md`).
3. Update the `## Notes` section with your hypothesis.
4. Reference the new preset via `warm with:` in your session message.
---
## The `warm with:` Bootstrap (the new mechanism)
In each `.warm.md` duplicate, the directive-reading portion of the pre-action reading list is replaced with this block:
```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.
```
The LLM reads the preset, then reads each variant file the preset references. This is the entire mechanism: one line (`warm with: <path>`) + the LLM's existing file-reading behavior.
### What was replaced (per role prompt)
| Role prompt | Section modified | Items replaced |
|---|---|---|
| tier1-orchestrator | "Session Start Checklist (MANDATORY)" | items 6-9 (data_oriented_design §8.5, python.md §17, type_aliases, error_handling) |
| tier2-tech-lead | "CRITICAL: Read the canonical docs FIRST" + "Session Start Checklist (MANDATORY)" | items 6-9 in BOTH sections |
| tier3-worker | "Task Start Checklist (MANDATORY)" | items 2-3 (python.md §17, data_oriented_design §8.5) |
| tier4-qa | Context Amnesia "However (added 2026-06-27):" paragraph | the "must read" sentence (data_oriented_design §8.5 + python.md §17) |
| tier2-autonomous | "MANDATORY: Pre-Action Required Reading" | items 7-10 (data_oriented_design §8.5, python.md §17, type_aliases, error_handling) |
### What stays hardcoded (per the user directive's "What stays hardcoded" list)
- `AGENTS.md` — project operating rules (in the role prompts that reference it)
- `conductor/workflow.md` — operational workflow
- `conductor/edit_workflow.md` — edit tool contract
- `conductor/tier2/githooks/forbidden-files.txt` — file denylist (only in tier2-autonomous which already references it)
- `conductor/tracks/tier2_leak_prevention_20260620/spec.md` — the prior leak incident (only in tier2-autonomous which already references it)
- The relevant `docs/guide_*.md` — architecture reference
- Other context docs (conductor/product.md, conductor/tech-stack.md, conductor/product-guidelines.md) — kept as direct references in the role prompts that already have them
---
## Phase 3 Verification (all 5 criteria PASS)
Detailed verification report: `docs/reports/phase3_verification_directive_hotswap_harness_20260627.md`
1. **53 entries in conductor/directives/** (51 directive dirs + presets/ + HARVEST_SUMMARY.md) ✓
2. **51 v1.md files**
3. **`conductor/directives/presets/current_baseline.md` exists** ✓
4. **5 `.warm.md` role-prompt duplicates exist** (4 in `.opencode/agents/`, 1 in `conductor/tier2/agents/`) ✓
5. **5 originals UNTOUCHED** (verified via `git diff e13d8b9b..HEAD --` showing zero changes) ✓
---
## The 2 User Directives Applied (2026-07-02)
### Directive 1: `.warm.md` duplicates, NOT in-place edits
The 5 role prompts' "directive-reading portions" were replaced ONLY in `.warm.md` duplicates. The 5 ORIGINAL `.md` role prompts are untouched. The user can `mv <name>.warm.md <name>.md` to promote or `rm <name>.warm.md` to fall back.
### Directive 2: NEVER run `scripts/audit/generate_chronology.py`
The chronology regen script corrupts Unicode characters (em-dashes, ellipses, BOM markers all become mojibake — verified 2026-07-02 when commit `bfebb718` had to be reverted). DO NOT run it. **The user will regenerate the chronology manually.** `conductor/chronology.md` is NOT updated as part of this track.
---
## What's NOT Included (out of scope per spec §"Out of Scope")
- **No alternative encodings (v2+ variants).** This track only creates v1 (verbatim lifts). The experimentation is a future activity (`directive_encoding_experiments` track).
- **No scripts.** No automation. No build steps.
- **No TOML.** Markdown-only.
- **No Manual Slop GUI integration.** The harness is OpenCode-only for now.
- **No token-cost analysis.** No tooling to measure token cost per variant.
- **No automated compliance testing.** No test harness to measure LLM compliance per encoding.
- **No Phase 3 §3.2 manual verification.** This is deferred to the user — it requires a live OpenCode session to observe whether the LLM follows the `warm with:` instruction.
---
## Drift Observations (NOT fixed in this track — separate concern)
These are observations from reading the role prompts during Phase 2 implementation. They are listed for future-tracks' awareness but are NOT fixed here per the user directive's "do NOT modify the originals" rule.
1. **tier3-worker line 94-101 inline banned-patterns enumeration** is now somewhat redundant with the warm-with bootstrap (the LLM reads the preset which contains the same banned patterns). Future preset authoring could decide whether to keep this inline list or rely solely on the warm-with.
2. **tier3-worker line 38 "Read them BEFORE implementing, especially the LLM Default Anti-Patterns in `conductor/code_styleguides/python.md` §17"** is a "must read"-style inline reference in the Context Amnesia section. Did NOT match the user directive's "MANDATORY: Pre-Action Required Reading" section pattern, so kept. Future cleanup could remove this.
3. **tier2-autonomous lines 54-70 "MANDATORY: The Banned Patterns" section** is now somewhat redundant with the warm-with bootstrap (the LLM reads the preset which contains the same banned patterns). Kept per user directive "Every OTHER section stays byte-identical".
4. **tier2-autonomous line 56 "From `conductor/code_styleguides/python.md` §17"** is a single inline reference within the banned-patterns section's lead sentence. Kept per user directive (single inline reference is not a "directives-listing block").
5. **tier2-autonomous surrounding prose "the agent's first action in any new track must be to read all 11 files and acknowledge them in the commit message"** is now slightly inaccurate — the .warm.md version should commit to reading the preset instead, not "all 11 files". Kept verbatim per user directive.
6. **tier2-tech-lead prompt does NOT currently mention `conductor/tier2/githooks/forbidden-files.txt` or `conductor/edit_workflow.md`.** The user directive's "What stays hardcoded" list includes these for tier2-tech-lead, but the original doesn't reference them. Per "Every OTHER section stays byte-identical", the duplicate doesn't add them. Future track could add them.
7. **tier4-qa Context Amnesia section's resulting structure** has the warm with: H2 block nested between two paragraphs of the section's prose, which creates a minor hierarchy oddity (the warm with: block's H2 is at the same level as "## Context Amnesia" itself). Acceptable for now.
---
## Handoff to Future Tracks
Per `metadata.json` `deferred_to_followup_tracks`:
1. **Alternative encoding authoring (v2+ variants).** Author `v2_rationale_first.md`, `v3_before_after.md`, `v4_tabular.md` etc. per directive. The actual experimentation. Test alternative encodings against the v1 baseline. Update preset files to swap variants.
2. **Manual Slop Directive Lab (GUI integration).** A "Directive Lab" panel in Manual Slop for virtualized directive selection + context aggregation. Per-track directive editing.
3. **Token-cost analysis tooling.** Measure token cost per directive variant. Compare compliance vs token cost.
4. **Automated compliance testing.** Test harness to measure LLM compliance per encoding (does the LLM follow the directive?). Run the same task across multiple variants; measure compliance delta.
5. **Video Analysis Campaign 2 (4 new videos).** Separate campaign; follows the 3-pass pattern. May inform alternative encoding strategies.
---
## Commit Summary (Phase 2 + Phase 3, this track end-to-end)
Phase 2 commits (this report's scope):
1. `2ddaeb52` — feat(directives): add current_baseline preset (51 directives, all v1) — also flipped state.toml phase_2 to in_progress (1 line scope drift, accepted)
2. `35831084` — feat(role-prompts): add tier1-orchestrator.warm.md duplicate with warm-with: bootstrap
3. `b082cb15` — feat(role-prompts): add tier2-tech-lead.warm.md duplicate with warm-with: bootstrap (TWO sections replaced)
4. `40764252` — feat(role-prompts): add tier3-worker.warm.md duplicate with warm-with: bootstrap
5. `b2aebbc9` — feat(role-prompts): add tier4-qa.warm.md duplicate with warm-with: bootstrap
6. `7b0d1164` — feat(role-prompts): add tier2-autonomous.warm.md duplicate with warm-with: bootstrap
7. `6ba4bdd` — feat(role-prompts): add 5 .warm.md duplicates (combined summary meta-commit; empty because all 5 files were committed atomically in steps 2-6)
Phase 3 commits (this report's scope):
8. `bbbfbd39` — conductor(verify): Phase 3 §3.1 directory structure verification — all 5 criteria match
9. (this commit) — docs(reports): TRACK_COMPLETION_directive_hotswap_harness_20260627
**Total Phase 2 + Phase 3 commits: 9** (matches user directive's expected "~9").
Each Phase 2 commit has a `git notes` annotation explaining what was replaced and what stayed in the .warm.md duplicate.
---
## Final State of `state.toml`
The state.toml will be updated atomically with this end-of-track report commit to reflect Phase 2 completion and Phase 3 entry. Phase 3 §3.2 is deferred to user.
---
## Chronology
**NOT REGENERATED.** Per user directive (2026-07-02): NEVER run `scripts/audit/generate_chronology.py`. The user will regenerate `conductor/chronology.md` manually. This track does NOT touch the chronology.