diff --git a/conductor/tracks/directive_hotswap_harness_20260627/dispatch_tier3_phase1.md b/conductor/tracks/directive_hotswap_harness_20260627/dispatch_tier3_phase1.md new file mode 100644 index 00000000..177329cb --- /dev/null +++ b/conductor/tracks/directive_hotswap_harness_20260627/dispatch_tier3_phase1.md @@ -0,0 +1,228 @@ +Track: directive_hotswap_harness_20260627 +Plan: conductor/tracks/directive_hotswap_harness_20260627/plan.md +Spec: conductor/tracks/directive_hotswap_harness_20260627/spec.md +State: conductor/tracks/directive_hotswap_harness_20260627/state.toml + +You are executing Phase 1 (Directive Harvest) of the harness plan. +This is a docs-only track — the artifacts are markdown files under +conductor/directives/. No src/*.py code changes in this phase. + +# Pre-flight (MANDATORY before any edit) + +1. Read conductor/tracks/directive_hotswap_harness_20260627/spec.md in full (verbatim, do not paraphrase). +2. Read conductor/tracks/directive_hotswap_harness_20260627/plan.md in full. +3. Read conductor/tracks/directive_hotswap_harness_20260627/state.toml — update current_phase from 0 to 1 when starting; advance task statuses as you complete each. +4. Update conductor/index.md's "Last comprehensive doc refresh" date if you touch any guide. +5. Update conductor/tracks.md to add `directive_hotswap_harness_20260627` row in the Standby section IF NOT already present. CHECK FIRST. +6. Read `conductor/code_styleguides/python.md` §17 once for the verbatim source text you'll be lifting (the plan's line refs were updated 2026-07-02; verify they still match by get_file_slice, do not trust the plan blindly). + +# Atomic per-task commits (HARD RULE) + +- ONE task = ONE commit. No batching. +- Every commit MUST be atomic per the project's commit discipline (see conductor/workflow.md §"AT THE END OF EACH TASK"). +- Per-task git notes are REQUIRED: see step 10 in workflow.md §"Standard Task Workflow". +- Use Conventional Commits prefix `feat(directives):` for the harvest commits and `docs(role-prompts):` for Phase 2. + +# Phase 1 tasks (follow plan §1.1 through §1.11 in order) + +For EACH plan task (t1_1 through t1_10), the directive creates N variant +files. For each v1.md file: + +1. Source the directive text via `get_file_slice` (the line range the + plan provides is the planner's best estimate; verify against current + line numbers via `grep -n` first). +2. Create `conductor/directives//v1.md` using the EXACT format from + the plan (the variant header format block under t1_1). +3. The variant content is a VERBATIM lift of the source text — NOT a + rewrite. The harvester is documenting current state. +4. After each batch of v1.md files (per plan step), run `git add` + + `git commit` with message: `feat(directives): harvest + directives from (§)`. + +The current line refs in plan.md (post 2026-07-02 drift-fix) are: + +- python.md §17: 243-473. The 7 banned patterns + §17.7 boundary exception + §17.8 enforcement + §17.9 local imports + §17.10 enforcement inventory. +- python.md §17.1 ban_dict_any: 247-264 +- python.md §17.2 ban_any_type: 266-277 +- python.md §17.3 ban_optional_returns: 279-299 +- python.md §17.4 ban_hasattr_dispatch: 301-326 +- python.md §17.5 ban_getattr_dispatch: 328-338 +- python.md §17.6 ban_dict_get_on_known_fields: 340-350 +- python.md §17.7 boundary_layer_exception: 352-354 +- python.md §17.9 (all 3): 364-443 (covers §17.9a/17.9b/17.9c) +- python.md §1-§2 (one_space_indent + type_hints_required pieces): 7-31 +- python.md §8 (no_comments, no_diagnostic_noise): 64-71 +- python.md §12 (sdm_dependency_tags): 202-211 +- python.md §13 (vertical_compaction): 212-224 +- python.md §15 (modular_controller_pattern): 234-241 +- error_handling.md §1 (The 5 Patterns): 22-131 +- error_handling.md §2 (Hard Rules): 212-264 +- error_handling.md §3 (Boundary Types): 284-365 +- data_oriented_design.md §8.5-8.7: 176-215 +- type_aliases.md (the per-aggregate pattern + promotion rules): 13-160 + +Verify each before lifting. If a line range has drifted, fix it in +the v1.md's header (the "Source:" line) to reflect the actual range +you lifted from. Do not propagate stale refs into the harvest. + +# Spec amendments made 2026-07-02 (during drift audit) + +The drift audit (11 commits f463edf9..6f4832b6) added 5 new styleguides +to the spec's "Sources to comb" list (in the spec file itself — verify +the edit landed at spec.md line ~134-156). The 5 new sources are: + +- conductor/code_styleguides/config_state_owner.md — AppController is single source of truth for config I/O +- conductor/code_styleguides/workspace_paths.md — test infrastructure paths must live under ./tests/ +- conductor/code_styleguides/test_sandbox.md — FR1/FR2/FR3 test sandbox conventions +- conductor/code_styleguides/chroma_cache.md — ChromaDB cache conventions +- conductor/code_styleguides/code_path_audit.md — per-aggregate data pipeline audit convention + +**Before lifting from any of these 5, read the file first** to determine +if it contains directive-like content (imperative/ban/preference). If +purely descriptive, SKIP and add a note to t1_11's commit body listing +which were skipped and why. This may bump the directive count below +the plan's 48. + +Also note that the audit found that `conductor/code_styleguides/python.md` +§17.8 and §17.10 referenced `audit_optional_returns.py` which does NOT +exist (corrected in commit 9d1fef73 to `audit_optional_in_3_files.py`). +When you lift §17.8 enforcement content, use the CURRENT version (the +post-fix python.md), not the pre-fix version. + +# Phase 1 task order + +Strictly sequential (each step depends on the prior): + +t1_1 → §17 banned patterns (7 directives; ban_dict_any..boundary_layer_exception) +t1_2 → §17.9 import/aliasing bans (3 directives) +t1_3 → Error handling conventions (2 directives) +t1_4 → Type/data-structure conventions (3 directives; updates boundary_layer_exception) +t1_5 → Code style directives (5 directives) +t1_6 → File/taxonomy conventions (3 directives) +t1_7 → Process/workflow directives (10 directives) +t1_8 → Process anti-patterns (6 directives) +t1_9 → GUI/architecture directives (5 directives) +t1_10 → Feature-flag + RAG + cache + knowledge directives (4 directives) +t1_11 → Commit the harvest (one final commit summarizing the 48 lifted v1.md files) + +After t1_11: per state.toml, advance current_phase to 2 (mark phase_1 +complete = true via the verification table). + +# Phase 2 (do NOT execute yet) + +After Phase 1 completes, you STOP and report back to the Tier 2 Tech +Lead. Phase 2 (baseline preset + role-prompt warm-with: bootstrap) +requires the Tier 2's review and decision on per-tier preset variants +before dispatching Tier 3 again. Do not auto-execute Phase 2. + +# Conventions (mandatory per the project's data-oriented styleguide) + +- 1-space indentation for Python (you won't write any Python here; this + is a docs-only track). +- No diagnostic stderr writes. +- No new src/*.py files. +- NO COMMENTS in the v1.md files unless the source doc had comments + (verbatim lifts preserve everything). Actually — VERBATIM means + the directive text INCLUDING any formatting/headers the source has. +- Each v1.md's `**Source:**` line is metadata about where the directive + came from, so it's fine to add (it's not a comment about your code). + +# Skill activation + +Before any action: `activate_skill mma-orchestrator`. Then activate +the sub-skill pattern by following the role-prompt warm-up rules +(currently the role prompts hardcode ~11 files to read; just read +those 11 files yourself). + +# Acknowledgment + +After completing the dispatch: +1. Update `conductor/tracks/directive_hotswap_harness_20260627/state.toml`: + - current_phase: 1 -> 2 + - phase_1.complete = true + - phase_1.checkpointsha = + - task t1_1 through t1_11 complete with respective commit hashes +2. Run `uv run python scripts/audit/generate_chronology.py --draft > + conductor/chronology.md` to regenerate (per workflow.md Chronology + Maintenance section). +3. Run the chronology quality gate: `uv run python -m + scripts.audit.chronology_quality_gate --strict` (must exit 0 before + the regenerated-chronology commit). +4. Commit the regenerated chronology. +5. Hand off to Tier 2 with a summary. + +# Files you'll touch + +- NEW: conductor/directives/<48 names>/v1.md (per the plan; possibly fewer + if the 5 new styleguides have no directive content) +- NEW: conductor/directives/presets/current_baseline.md (Phase 2 — NOT YET) +- MODIFIED: conductor/tracks/directive_hotswap_harness_20260627/state.toml +- MODIFIED (regenerated): conductor/chronology.md + +# Coverage contract + +The track's verification_criteria (per metadata.json, when you read it) +will assert: +- directive_count == 48 (or fewer if you skip any of the 5 new styleguides) +- phase_1_complete == true +- role_prompts_updated == false (that's Phase 2, NOT yet) +- preset_exists == false (that's Phase 2, NOT yet) + +If verification_criteria has other fields, address each. + +# COMMIT / GIT NOTE discipline + +Every commit MUST have a git note attached. See conductor/workflow.md +§"Standard Task Workflow" step 10 for the format. The git note content +must include: +- Task name + number +- Files touched (with line counts) +- The core "why" + +Use `git notes add -m "..." ` after each commit. + +# Deliverables per task + +For each lifted v1.md: +1. The v1.md file at conductor/directives//v1.md +2. The atomic commit +3. The git note + +For the Phase 1 checkpoint commit (t1_11): +- One commit covering t1_11's summarization (or N commits, one per + lifted group, then t1_11 as the meta summary) +- The git note summarizing the harvest + +After Phase 1 done: +- Updated state.toml +- Regenerated chronology.md +- Updated chronology quality gate committed + +# STOP AFTER PHASE 1 + +Per the "Phase 2 do NOT execute yet" rule above, stop and hand off. + +If you encounter blockers that the plan does not cover: +- File drift the plan does not address +- Directive ambiguity (merge/split/keep) +- Styleguide content where the directive nature is unclear + +Report the blocker with file:line evidence and let Tier 2 decide. + +# Per-skill activation note + +This task does NOT require `mma-tier1-orchestrator` (you are not +creating a new track — the track is already initialized). It DOES +require `mma-tier2-tech-lead` (you are executing the plan). Activate it. + +# Final note + +USE EXACTLY 1-SPACE INDENTATION FOR PYTHON IF YOU WRITE ANY. You +shouldn't be writing Python for this task — it's markdown only — but if +you do write any tooling or verification scripts, 1-space it. + +NEVER use `git checkout -- `, `git restore`, or `git reset` +without explicit user permission. See AGENTS.md for the ban list. + +NEVER filter test output through Select-Object/head/tail per +AGENTS.md. Redirect to a log file. \ No newline at end of file diff --git a/conductor/tracks/directive_hotswap_harness_20260627/state.toml b/conductor/tracks/directive_hotswap_harness_20260627/state.toml index 5fdd1906..3fa99b9f 100644 --- a/conductor/tracks/directive_hotswap_harness_20260627/state.toml +++ b/conductor/tracks/directive_hotswap_harness_20260627/state.toml @@ -7,8 +7,8 @@ track_id = "directive_hotswap_harness_20260627" name = "Directive Hot-Swap Harness (OpenCode Directive Presets)" status = "active" -current_phase = 0 -last_updated = "2026-06-27" +current_phase = 1 +last_updated = "2026-07-02" [blocked_by] # None. Pure documentation/track-artifact work; no code changes, no tests, @@ -19,7 +19,7 @@ directive_encoding_experiments = "planned (future; v2+ variant authoring)" manual_slop_directive_lab = "planned (future; GUI integration)" [phases] -phase_1 = { status = "pending", checkpointsha = "", name = "Directive Harvest (10 steps: 48 directives from doc tree into conductor/directives/)" } +phase_1 = { status = "in_progress", checkpointsha = "", name = "Directive Harvest (10 steps: 48 directives from doc tree into conductor/directives/)" } phase_2 = { status = "pending", 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)" }