From c9f30abffc026ebc6b834d1b39590568b9d216fd Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 2 Jul 2026 23:27:25 -0400 Subject: [PATCH] docs(reports): TRACK_COMPLETION_directive_hotswap_harness_20260627 --- .../state.toml | 45 ++-- ...TION_directive_hotswap_harness_20260627.md | 247 ++++++++++++++++++ 2 files changed, 271 insertions(+), 21 deletions(-) create mode 100644 docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md diff --git a/conductor/tracks/directive_hotswap_harness_20260627/state.toml b/conductor/tracks/directive_hotswap_harness_20260627/state.toml index 6f9bf2eb..a2f2d8e3 100644 --- a/conductor/tracks/directive_hotswap_harness_20260627/state.toml +++ b/conductor/tracks/directive_hotswap_harness_20260627/state.toml @@ -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)" diff --git a/docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md b/docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md new file mode 100644 index 00000000..1e56ff32 --- /dev/null +++ b/docs/reports/TRACK_COMPLETION_directive_hotswap_harness_20260627.md @@ -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//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: ` 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: `) + 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 .warm.md .md` to promote or `rm .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. \ No newline at end of file