diff --git a/conductor/directives/atomic_per_task_commits/v1.md b/conductor/directives/atomic_per_task_commits/v1.md new file mode 100644 index 00000000..7cedd46f --- /dev/null +++ b/conductor/directives/atomic_per_task_commits/v1.md @@ -0,0 +1,19 @@ +# atomic_per_task_commits — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Standard Task Workflow" step 9 (line 112) + `AGENTS.md` "Critical Anti-Patterns" (line 55). This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, before/after) against this baseline. + +**Source:** `conductor/workflow.md:112 + AGENTS.md:55` + +--- + +From `conductor/workflow.md` §"Standard Task Workflow" step 9: +- **CRITICAL - ATOMIC PER-TASK COMMITS**: You MUST commit your changes immediately after completing and verifying a single task. Do NOT move on to the next task in the plan without committing the current one. This ensures precise tracking and safe rollback points. +- Stage all code changes related to the task. +- Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`. +- Perform the commit. + +--- + +From `AGENTS.md` "Critical Anti-Patterns": +- Do not batch commits - commit per-task for atomic rollback \ No newline at end of file diff --git a/conductor/directives/ban_arbitrary_core_mocking/v1.md b/conductor/directives/ban_arbitrary_core_mocking/v1.md new file mode 100644 index 00000000..3237f357 --- /dev/null +++ b/conductor/directives/ban_arbitrary_core_mocking/v1.md @@ -0,0 +1,18 @@ +# ban_arbitrary_core_mocking — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Structural Testing Contract" #1 (line 262) + `AGENTS.md` §"Critical Anti-Patterns" (line 53). This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, before/after) against this baseline. + +**Source:** `conductor/workflow.md:262 + AGENTS.md:53` + +--- + +From `conductor/workflow.md` §"Structural Testing Contract": +1. **Ban on Arbitrary Core Mocking:** Tier 3 workers are strictly forbidden from using `unittest.mock.patch` to bypass or stub core infrastructure (e.g., event queues, `ai_client` internals, threading primitives) unless explicitly authorized by the Tier 2 Tech Lead for a specific boundary test. +2. **`live_gui` Standard:** All integration and end-to-end testing must utilize the `live_gui` fixture to interact with a real instance of the application via the Hook API. Bypassing the hook server to directly mutate GUI state in tests is prohibited. +3. **Artifact Isolation:** All test-generated artifacts (logs, temporary workspaces, mock outputs) MUST be written to the `tests/artifacts/` or `tests/logs/` directories. These directories are git-ignored to prevent repository pollution. + +--- + +From `AGENTS.md` "Critical Anti-Patterns": +- Do not skip TDD - write failing tests before implementing functionality \ No newline at end of file diff --git a/conductor/directives/ban_day_estimates/v1.md b/conductor/directives/ban_day_estimates/v1.md new file mode 100644 index 00000000..7b553a1a --- /dev/null +++ b/conductor/directives/ban_day_estimates/v1.md @@ -0,0 +1,30 @@ +# ban_day_estimates — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` "Critical Anti-Patterns" HARD BAN (line 61) + `conductor/workflow.md` §"Tier 1 Track Initialization Rules" §1 (lines 605-625). This is the baseline encoding — the imperative-bullet-with-rationale style currently in production. +Future variants will test alternative encodings (tabular, replacement-patterns-table) against this baseline. + +**Source:** `AGENTS.md:61 + workflow.md:605-625` + +--- + +From `AGENTS.md` "Critical Anti-Patterns": +- **HARD BAN: Day estimates in track artifacts (Tier 1).** Do NOT include day / hour / minute estimates in spec.md, plan.md, metadata.json, or any other track artifact. Day estimates are inaccurate noise; Tier 2 capacity is bounded by attention, not time. Measure effort by **scope** (N files, M sites, N tasks). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.") + +--- + +From `conductor/workflow.md` §"Tier 1 Track Initialization Rules" §1: +**HARD BAN.** Do NOT include day, hour, or minute estimates in +`spec.md`, `plan.md`, `metadata.json`, or any other track artifact. + +**Why:** day estimates are inaccurate noise. Tier 2 capacity is bounded +by **attention**, not time. A track that "should take 2 days" can take +half a day (if the user is available and the Tier 2 is focused) or 3 +days (if interruptions come up, the user is unavailable for review, or +the audit reveals scope growth). The Tier 1 cannot predict either +scenario. Estimates also anchor the user's expectations incorrectly; +"the spec said 2 days and it's been 3, what's wrong?". + +**What to use instead:** measure effort by **scope** (N files, M sites, +N tasks). No sizing labels (T-shirt sizes, points, day estimates) are +allowed in track artifacts - they are all guesses. The user / Tier 2 +agent decides the actual pacing. \ No newline at end of file diff --git a/conductor/directives/batch_verification_not_isolation/v1.md b/conductor/directives/batch_verification_not_isolation/v1.md new file mode 100644 index 00000000..cfe13078 --- /dev/null +++ b/conductor/directives/batch_verification_not_isolation/v1.md @@ -0,0 +1,14 @@ +# batch_verification_not_isolation — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Isolated-Pass Verification Fallacy (Added 2026-06-09)" (lines 510-514). This is the baseline encoding — the rationale-then-rule style currently in production. +Future variants will test alternative encodings (rule-only, before/after) against this baseline. + +**Source:** `conductor/workflow.md:510-514` + +--- + +### Isolated-Pass Verification Fallacy (Added 2026-06-09) + +A test that "passes when run after test X but fails in isolation" is a **fragile test, not a fragile fixture**. The flip side is also true: a test that "passes in isolation but fails in batch" is failing — its failure is masked by isolation. The only verification that matters for `live_gui` tests (or any test that depends on shared subprocess state) is the **batch run** in the suite the test will ship in. + +**Rule:** For any `live_gui` test or any test that depends on shared subprocess state, do NOT commit a fix that you have only verified in isolation. The fix must pass in the batched run that includes the tests that share the subprocess. Run the batch first. If the test fails in batch, your fix is incomplete. Per the existing `Live_gui Test Fragility (Authoring-Side)` rule above, the bisect requires both directions. If you only run in isolation, you cannot tell "test needs work" from "real app bug." \ No newline at end of file diff --git a/conductor/directives/git_hard_bans/v1.md b/conductor/directives/git_hard_bans/v1.md new file mode 100644 index 00000000..2eefcefa --- /dev/null +++ b/conductor/directives/git_hard_bans/v1.md @@ -0,0 +1,34 @@ +# git_hard_bans — v1 + +**Why this iteration:** Lifted verbatim from `AGENTS.md` "Critical Anti-Patterns" HARD BAN lines (59-60) + `conductor/workflow.md` §"Known Pitfalls" (lines 417-430). This is the baseline encoding — the imperative-bullet-with-rationale style currently in production. +Future variants will test alternative encodings (tabular, before/after) against this baseline. + +**Source:** `AGENTS.md:59-60 + workflow.md:417-430` + +--- + +From `AGENTS.md` "Critical Anti-Patterns" HARD BAN: +- HARD BAN: `git restore`, `git checkout -- `, `git reset` are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST. +- HARD BAN: `git stash*` (any form: `git stash`, `git stash pop`, `git stash apply`, `git stash drop`, `git stash clear`) is FORBIDDEN. Stashing inverts the safety net of the working tree: a `git add .` then `git stash` then "fresh start" pattern is exactly how Tier 2 corrupted files in the 2026-06-27 `cruft_elimination_20260627` track. The user explicitly stated "I hate when people fuck with my commits" — stashing throws away the user's in-progress edits silently. If you think you need a stash, you don't — use a NEW BRANCH or a WORKTREE instead. Tier 2 sandbox enforces this via `conductor/tier2/opencode.json.fragment` bash deny rules. + +--- + +From `conductor/workflow.md` §"Known Pitfalls (2026-06-05)" §"HARD BAN": +**Per AGENTS.md (Critical Anti-Patterns):** These three commands are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress `src/*` edits twice in one session (2026-06-07). If you think you need one, ASK FIRST. + +The intent of "look at what the file looked like at commit X" is non-destructive inspection. The CORRECT way: + +```bash +# WRONG: overwrites the working tree +git checkout HEAD~1 -- src/foo.py + +# RIGHT: prints to stdout, leaves working tree alone +git show HEAD~1:src/foo.py +``` + +`git checkout -- ` and `git restore` are particularly dangerous because: +- They overwrite uncommitted changes silently +- They overwrite previously-committed state in the working tree if the user has already committed and then re-edited +- The user doesn't see the loss until they notice missing changes + +If you genuinely need to revert (e.g., the working tree is broken from a previous agent), use `git stash` first to capture the in-progress state, ASK THE USER, then proceed. \ No newline at end of file diff --git a/conductor/directives/live_gui_poll_not_sleep/v1.md b/conductor/directives/live_gui_poll_not_sleep/v1.md new file mode 100644 index 00000000..9d725225 --- /dev/null +++ b/conductor/directives/live_gui_poll_not_sleep/v1.md @@ -0,0 +1,23 @@ +# live_gui_poll_not_sleep — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Live_gui Test Fragility (Authoring-Side)" — Anti-Pattern: push_event + time.sleep(N) + assert (lines 464-475). This is the baseline encoding — the rationale-then-before/after-example style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `conductor/workflow.md:464-475` + +--- + +#### Anti-Pattern: `push_event` + `time.sleep(N)` + `assert` is a guaranteed race (Added 2026-06-10) + +The pattern `push_event(...)` → `time.sleep(N)` → `assert` is a guaranteed race condition in batched runs. The first time you write this, the test passes in isolation because the sleep happens to be long enough. Then it lands in the batched run, the subprocess is busier, the sleep is no longer long enough, and the assert fires before the GUI render loop has processed the event. + +**Fix:** Replace `time.sleep(N)` with a poll loop on `get_value` or `wait_for_event`. The poll doubles as a wait-for-ready AND a correctness assertion. + +```python +# WRONG: race condition +def test_open_modal(live_gui): + client.push_event("custom_callback", {"callback": "_toggle_settings", "args": []}) + time.sleep(1) # hope the modal opened + assert some_cached_value["settings_open"] is True # may be stale + +# RIGHT: poll-until-state-visible \ No newline at end of file diff --git a/conductor/directives/mandatory_research_first/v1.md b/conductor/directives/mandatory_research_first/v1.md new file mode 100644 index 00000000..13348593 --- /dev/null +++ b/conductor/directives/mandatory_research_first/v1.md @@ -0,0 +1,16 @@ +# mandatory_research_first — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Guiding Principles" #9 (line 46) + `AGENTS.md` "Critical Anti-Patterns" (line 51). This is the baseline encoding — the imperative-rule-with-tools style currently in production. +Future variants will test alternative encodings (rule-only, tabular) against this baseline. + +**Source:** `conductor/workflow.md:46 + AGENTS.md:51` + +--- + +From `conductor/workflow.md` §"Guiding Principles" #9: +8. **Mandatory Research-First Protocol:** Before reading the full content of any file over 50 lines, you MUST use `get_file_summary`, `py_get_skeleton`, `py_get_code_outline`, or `py_get_docstring` to map the architecture and identify specific target ranges. Use `get_git_diff` to understand recent changes. Use `py_find_usages` to locate where symbols are used. + +--- + +From `AGENTS.md` "Critical Anti-Patterns": +- Do not read full files >50 lines without first using `py_get_skeleton` or `get_file_summary` to map the structure (this is navigation efficiency, not a "files should be small" stance) \ No newline at end of file diff --git a/conductor/directives/no_output_filtering/v1.md b/conductor/directives/no_output_filtering/v1.md new file mode 100644 index 00000000..7df6b8bc --- /dev/null +++ b/conductor/directives/no_output_filtering/v1.md @@ -0,0 +1,11 @@ +# no_output_filtering — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Tier 2 Autonomous Sandbox" §"Conventions" #2 (line 386). This is the baseline encoding — the imperative-rule-with-rationale style currently in production. +Future variants will test alternative encodings (rule-only, before/after) against this baseline. + +**Source:** `conductor/workflow.md:386` + +--- + +From `conductor/workflow.md` §"Tier 2 Autonomous Sandbox" §"Conventions" #2: +2. **NEVER filter test output** (added 2026-06-27 per user directive). Do NOT pipe test output through `Select-Object`, `| Select -First N`, `| Select -Last N`, `head`, `tail`, or any truncation filter. If you need to see more output later, you'll have to re-run the entire test — which wastes time and context. Instead, ALWAYS redirect to a log file: `uv run python scripts/run_tests_batched.py > tests/artifacts/tier2_state//test_run__.log 2>&1`. Then read the log file with `manual-slop_read_file` or `grep` to find the relevant sections. The log file is your full record; you can search it without re-running. \ No newline at end of file diff --git a/conductor/directives/prefer_targeted_tier_runs/v1.md b/conductor/directives/prefer_targeted_tier_runs/v1.md new file mode 100644 index 00000000..6dddda32 --- /dev/null +++ b/conductor/directives/prefer_targeted_tier_runs/v1.md @@ -0,0 +1,11 @@ +# prefer_targeted_tier_runs — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Tier 2 Autonomous Sandbox" §"Conventions" #3 (line 387). This is the baseline encoding — the imperative-rule-with-rationale style currently in production. +Future variants will test alternative encodings (rule-only, before/after) against this baseline. + +**Source:** `conductor/workflow.md:387` + +--- + +From `conductor/workflow.md` §"Tier 2 Autonomous Sandbox" §"Conventions" #3: +3. **Prefer targeted tier runs** (added 2026-06-27 per user directive). Do NOT run the full 11-tier batch for every verification. Run only the tiers relevant to the current task (e.g., `--tier tier3` or `--filter test_`). The full batch is for the USER to run after merge review, not for Tier 2's per-task verification. Running the full batch every time wastes 20+ minutes and the output is too large to be useful in context. \ No newline at end of file diff --git a/conductor/directives/tdd_red_green_required/v1.md b/conductor/directives/tdd_red_green_required/v1.md new file mode 100644 index 00000000..ea625ed6 --- /dev/null +++ b/conductor/directives/tdd_red_green_required/v1.md @@ -0,0 +1,27 @@ +# tdd_red_green_required — v1 + +**Why this iteration:** Lifted verbatim from `conductor/workflow.md` §"Standard Task Workflow" steps 4-6 (lines 78-100). This is the baseline encoding — the numbered-step style currently in production. +Future variants will test alternative encodings (rationale-first, tabular) against this baseline. + +**Source:** `conductor/workflow.md:78-100` + +--- + +4. **Write Failing Tests (Red Phase):** + - **Pre-Delegation Checkpoint:** Before spawning a worker for dangerous or non-trivial changes, ensure your current progress is staged (`git add .`) or committed. This prevents losing iterations if a sub-agent incorrectly uses `git restore`. + - **Zero-Assertion Ban:** You MUST NOT write tests that contain only `pass` or lack meaningful assertions. A test is only valid if it contains assertions that explicitly test the behavioral change and verify the failure condition. + - **Code Style:** ALWAYS explicitly mention "Use exactly 1-space indentation for Python code" when prompting a sub-agent. + - **Delegate Test Creation:** Do NOT write test code directly. Spawn a Tier 3 Worker via the **OpenCode Task tool** with `subagent_type: "tier3-worker"` and a **surgical prompt** specifying WHERE (file:line range), WHAT (test to create), HOW (which assertions/fixtures to use), and SAFETY (thread constraints if applicable). Example: `"Write tests in tests/test_cost_tracker.py for cost_tracker.py:estimate_cost(). Test all model patterns in MODEL_PRICING dict. Assert unknown model returns 0. Use 1-space indentation."` (If repeating due to failures, set the subagent's `failure_count` higher to switch to a more capable model.) **Note:** the legacy `python scripts/mma_exec.py --role tier3-worker` invocation is DEPRECATED (see §"Conductor Token Firewalling" below); use the OpenCode Task tool instead. + - Take the code generated by the Worker and apply it. + - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests. + +5. **Implement to Pass Tests (Green Phase):** + - **Pre-Delegation Checkpoint:** Ensure current progress is staged or committed before delegating. + - **Code Style:** ALWAYS explicitly mention "Use exactly 1-space indentation for Python code" when prompting a sub-agent. + - **Delegate Implementation:** Do NOT write the implementation code directly. Spawn a Tier 3 Worker via the **OpenCode Task tool** (`subagent_type: "tier3-worker"`) with a **surgical prompt** specifying WHERE (file:line range to modify), WHAT (the specific change), HOW (which API calls, data structures, or patterns to use), and SAFETY (thread-safety constraints). Example: `"In gui_2.py _render_mma_dashboard (lines 2685-2699), extend the token usage table from 3 to 5 columns by adding 'Model' and 'Est. Cost'. Use imgui.table_setup_column(). Import cost_tracker. Call cost_tracker.estimate_cost(model, input_tokens, output_tokens). Use 1-space indentation."` (If repeating due to failures, set `failure_count` higher to switch to a more capable model.) **Note:** the legacy `python scripts/mma_exec.py --role tier3-worker` invocation is DEPRECATED; use the OpenCode Task tool. + - Take the code generated by the Worker and apply it. + - Run the test suite again and confirm that all tests now pass. This is the "Green" phase. + +6. **Refactor (Optional but Recommended):** + - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior. + - Rerun tests to ensure they still pass after refactoring. \ No newline at end of file