refactor(directives): strip metadata header from v1.md (27-35 of 51; meta extracted to meta.md)

2026-07-02 23:46:41 -04:00
parent 831499622d
commit 68352ee206
18 changed files with 91 additions and 82 deletions
@@ -0,0 +1,10 @@
+# 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`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# 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.
@@ -0,0 +1,10 @@
+# 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`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# 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.

@@ -0,0 +1,10 @@
+# metadata_boundary_type
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/data_oriented_design.md` §8.6 (lines 200-202) + `conductor/code_styleguides/type_aliases.md` §"The 5 Decision Patterns" #1 + #2.5 (lines 54-132). This is the baseline encoding — the prose-then-code-example style currently in production.
+Future variants will test alternative encodings (rule-list, before/after only) against this baseline.
+**Source:** `conductor/code_styleguides/data_oriented_design.md:200-202 + type_aliases.md:54-132`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# metadata_boundary_type — v1
-
-**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/data_oriented_design.md` §8.6 (lines 200-202) + `conductor/code_styleguides/type_aliases.md` §"The 5 Decision Patterns" #1 + #2.5 (lines 54-132). This is the baseline encoding — the prose-then-code-example style currently in production.
-Future variants will test alternative encodings (rule-list, before/after only) against this baseline.
-
-**Source:** `conductor/code_styleguides/data_oriented_design.md:200-202 + type_aliases.md:54-132`
-
---
-
 ### 8.6 The Boundary Layer (the wire schema)

 The codebase has ONE typed fat struct at the boundary: `Metadata` in `src/type_aliases.py`. It is `@dataclass(frozen=True, slots=True)` with explicit fields covering the TOML/JSON wire schema (paths, project, discussion, role, content, ts, source_tier, model, depends_on, document, script, args, etc.). It is used in exactly 2 places:
@@ -0,0 +1,10 @@
+# modular_controller_pattern
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `conductor/product-guidelines.md` §"Code Standards & Architecture" (line 40) + `conductor/code_styleguides/python.md` §15 (lines 234-240). This is the baseline encoding — the imperative-bullet style currently in production.
+Future variants will test alternative encodings (rationale-first, tabular) against this baseline.
+**Source:** `conductor/product-guidelines.md:40 + python.md:234-240`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# modular_controller_pattern — v1
-
-**Why this iteration:** Lifted verbatim from `conductor/product-guidelines.md` §"Code Standards & Architecture" (line 40) + `conductor/code_styleguides/python.md` §15 (lines 234-240). This is the baseline encoding — the imperative-bullet style currently in production.
-Future variants will test alternative encodings (rationale-first, tabular) against this baseline.
-
-**Source:** `conductor/product-guidelines.md:40 + python.md:234-240`
-
---
-
 From `conductor/product-guidelines.md` §"Code Standards & Architecture":
 - **Modular Controller Pattern:** To prevent "God Object" bloat in core controllers (like `AppController`), all state-independent or utility logic must be moved to module-level functions. Functions requiring class state should accept the instance as an explicit dependency (`def logic(controller: AppController, ...)`). Massive `if/elif` dispatch blocks must be refactored into handler maps (dictionaries) of module-level functions.

@@ -0,0 +1,11 @@
+# nil_sentinel_pattern
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/error_handling.md` §"The 5 Patterns" #1 (lines 23-47).
+This is the baseline encoding — the convention-style description with code example currently in production.
+Future variants will test alternative encodings (rationale-first, before/after, tabular) against this baseline.
+**Source:** `conductor/code_styleguides/error_handling.md:23-47`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,13 +1,3 @@
-# nil_sentinel_pattern — v1
-
-**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/error_handling.md` §"The 5 Patterns" #1 (lines 23-47).
-This is the baseline encoding — the convention-style description with code example currently in production.
-Future variants will test alternative encodings (rationale-first, before/after, tabular) against this baseline.
-
-**Source:** `conductor/code_styleguides/error_handling.md:23-47`
-
---
-
 ### 1. Nil-Sentinel Dataclasses (replaces `None`)

 When a function would "return None" in conventional Python, return a
@@ -0,0 +1,10 @@
+# no_comments_in_body
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §8 (lines 64-71) + `AGENTS.md` "Critical Anti-Patterns" (line 54). 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/code_styleguides/python.md:64-71 + AGENTS.md:54`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# no_comments_in_body — v1
-
-**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §8 (lines 64-71) + `AGENTS.md` "Critical Anti-Patterns" (line 54). 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/code_styleguides/python.md:64-71 + AGENTS.md:54`
-
---
-
 From `conductor/code_styleguides/python.md` §8 "AI-Agent Specific Conventions":
 - **No redundant comments.** Do not add comments that restate what the code does. Only comment on *why* when non-obvious.

@@ -0,0 +1,10 @@
+# no_diagnostic_noise
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §8 (lines 68-70) + `AGENTS.md` "Session-Learned Anti-Patterns" §5. 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/code_styleguides/python.md:68-70 + AGENTS.md:"Session-Learned Anti-Patterns" §5`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# no_diagnostic_noise — v1
-
-**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §8 (lines 68-70) + `AGENTS.md` "Session-Learned Anti-Patterns" §5. 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/code_styleguides/python.md:68-70 + AGENTS.md:"Session-Learned Anti-Patterns" §5`
-
---
-
 From `conductor/code_styleguides/python.md` §8 "AI-Agent Specific Conventions":
 - **No diagnostic noise in production code (Added 2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...")` lines added to `src/*.py` for one-time debugging are technical debt the moment they ship. The project's production code should not contain `[XYZ_DIAG]` markers, `print(...debug...)` calls, or any other ad-hoc debug instrumentation. The right place for diagnostic output during a one-time investigation is `tests/artifacts/<test_name>.diag.log` (a log file) or a standalone `/tmp/diag_<name>.py` script. If you must instrument a production function for a single test run, the diag lines are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. If you "revert everything," that means the diag lines are also reverted.

@@ -0,0 +1,10 @@
+# no_new_src_files_without_permission
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `AGENTS.md` "Hard rule on creating new `src/<thing>.py` files (added 2026-06-11)" (lines 71-78). This is the baseline encoding — the rationale-bullet style currently in production.
+Future variants will test alternative encodings (tabular, before/after) against this baseline.
+**Source:** `AGENTS.md:71-78`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,12 +1,3 @@
-# no_new_src_files_without_permission — v1
-
-**Why this iteration:** Lifted verbatim from `AGENTS.md` "Hard rule on creating new `src/<thing>.py` files (added 2026-06-11)" (lines 71-78). This is the baseline encoding — the rationale-bullet style currently in production.
-Future variants will test alternative encodings (tabular, before/after) against this baseline.
-
-**Source:** `AGENTS.md:71-78`
-
---
-
 ### Hard rule on creating new `src/<thing>.py` files (added 2026-06-11)

 **New namespaced `src/<thing>.py` files may only be created on the user's explicit request.** If you find yourself about to create one, **ASK FIRST** — don't just create it.
@@ -0,0 +1,10 @@
+# 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`
+
+---
+**Lifted:** 2026-07-02 (Phase 1 harvest by Tier 3 worker; user directive 2026-07-02 moved the header into this meta file)
@@ -1,11 +1,2 @@
-# 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/<track>/test_run_<phase>_<task>.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.