Private
Public Access
docs: scrub gemini_cli references from 12 docs (provider count 8->7)
Cleaned: docs/guide_ai_client.md, docs/guide_architecture.md, docs/guide_models.md, docs/guide_simulations.md, docs/guide_context_aggregation.md, docs/guide_tools.md, docs/Readme.md, conductor/tech-stack.md, conductor/product.md, conductor/product-guidelines.md, conductor/workflow.md, conductor/code_styleguides/error_handling.md. Provider list citations updated to 7 (gemini, anthropic, deepseek, minimax, qwen, grok, llama). guide_meta_boundary.md intentionally retained (its gemini_cli references are the meta-tooling GEMINI_CLI_HOOK_CONTEXT env var, NOT the provider; per spec GAP-A12).
This commit is contained in:
+198
-198
@@ -42,10 +42,10 @@ Or use Python subprocess with `newline=''` to preserve line endings:
|
||||
```python
|
||||
python -c "
|
||||
with open('file.py', 'r', encoding='utf-8', newline='') as f:
|
||||
content = f.read()
|
||||
content = f.read()
|
||||
content = content.replace(old, new)
|
||||
with open('file.py', 'w', encoding='utf-8', newline='') as f:
|
||||
f.write(content)
|
||||
f.write(content)
|
||||
"
|
||||
```
|
||||
|
||||
@@ -61,19 +61,19 @@ with open('file.py', 'w', encoding='utf-8', newline='') as f:
|
||||
8. **File Naming Convention (HARD RULE, added 2026-06-11):** New `src/<thing>.py` files may only be created on the user's explicit request. Helpers and sub-systems go in the parent module. E.g., AI-client-specific code goes in `src/ai_client.py`; MCP-client code goes in `src/mcp_client.py`. If you find yourself about to create a new `src/<thing>.py` file, ASK FIRST. See `AGENTS.md` "File Size and Naming Convention" for the full rule.
|
||||
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.
|
||||
9. **Architecture Documentation Fallback:** When uncertain about threading, event flow, data structures, or module interactions, consult the deep-dive docs in `docs/` (last refreshed: 2026-06-02 via the comprehensive documentation refresh track, **8 new guides added**):
|
||||
- **[docs/guide_architecture.md](../docs/guide_architecture.md):** Thread domains, cross-thread patterns, AI client multi-provider (Gemini, Anthropic, DeepSeek, Gemini CLI, MiniMax), HITL Execution Clutch.
|
||||
- **[docs/guide_tools.md](../docs/guide_tools.md):** MCP Bridge 3-layer security, full 45-tool inventory, Hook API, ApiHookClient, `/api/ask` HITL protocol.
|
||||
- **[docs/guide_mma.md](../docs/guide_mma.md):** Ticket/Track/WorkerContext data structures, DAG engine, ConductorEngine, Tier 2/3/4 lifecycles, persona application.
|
||||
- **[docs/guide_simulations.md](../docs/guide_simulations.md):** `live_gui` fixture, Puppeteer pattern, mock provider, test areas by subsystem.
|
||||
- **[docs/guide_testing.md](../docs/guide_testing.md):** **NEW** — 251 test files, 5 categories, 7 conftest fixtures (`isolate_workspace`, `reset_paths`, `reset_ai_client`, `vlogger`, `kill_process_tree`, `mock_app`, `live_gui` session-scoped), Puppeteer pattern, mock provider, structural testing contract.
|
||||
- **[docs/guide_gui_2.md](../docs/guide_gui_2.md):** **NEW** — `src/gui_2.py` (~437KB main GUI): App class lifecycle, ~90 module-level render functions, Multi-Viewport docks, panel registry, command palette integration, ImGuiScope context managers, hot reload support.
|
||||
- **[docs/guide_ai_client.md](../docs/guide_ai_client.md):** **NEW** — `src/ai_client.py` (~166KB): multi-provider LLM singleton (8 providers: gemini, anthropic, gemini_cli, deepseek, minimax, qwen, grok, llama), async dispatch via `asyncio.gather`, threading.local for source tier tagging, Anthropic ephemeral caching + Gemini explicit caching, Tier 4 QA error interception, inlined `VendorCapabilities` registry (moved from the deleted `src/vendor_capabilities.py`).
|
||||
- **[docs/guide_api_hooks.md](../docs/guide_api_hooks.md):** **NEW** — `src/api_hooks.py` + `src/api_hook_client.py` (~51KB + ~38KB): HookServer on `127.0.0.1:8999`, ApiHookClient wrapper, 8+ endpoints, Remote Confirmation Protocol via `/api/ask`.
|
||||
- **[docs/guide_mcp_client.md](../docs/guide_mcp_client.md):** **NEW** — `src/mcp_client.py` (~92KB, 45 tools; tool specs live in `src/mcp_tool_specs.py`): 3-layer security (Allowlist → Validate → Resolve), all native tools (File I/O, Python AST, C/C++ AST, Analysis, Network, Runtime, Beads), ExternalMCPManager (Stdio + SSE), JSON-RPC 2.0 engine.
|
||||
- **[docs/guide_app_controller.md](../docs/guide_app_controller.md):** **NEW** — `src/app_controller.py` (~240KB): headless orchestrator, AppState dataclass, all subsystem managers, `_predefined_callbacks`/`_gettable_fields` Hook API registries, SyncEventQueue, headless mode.
|
||||
- **[docs/guide_multi_agent_conductor.md](../docs/guide_multi_agent_conductor.md):** **NEW** — `src/multi_agent_conductor.py` + `src/dag_engine.py` (~30KB + ~11KB): TrackDAG (iterative DFS cycle detection, Kahn's topological sort), ExecutionEngine (Auto-Queue / Step Mode), MultiAgentConductor + WorkerPool (concurrency 4), the WorkerPool's internal `run_worker_lifecycle` subprocess template (NOT the deprecated `mma_exec.py`; see `docs/guide_meta_boundary.md`).
|
||||
- **[docs/guide_models.md](../docs/guide_models.md):** **UPDATED 2026-07-02** — `src/models.py` is now a ~1.5KB legacy re-export shim (`Metadata = TrackMetadata` alias + `PROVIDERS` lazy `__getattr__`). Data models moved to per-system files per `module_taxonomy_refactor_20260627`: `src/mma.py` (TrackMetadata, Ticket, Track, WorkerContext), `src/project_files.py` (FileItem), `src/type_aliases.py` (typed boundary + per-aggregate dataclasses), `src/mcp_tool_specs.py` (typed ToolSpec registry, 45 tools), `src/result_types.py` (Result[T], ErrorInfo). `VendorCapabilities` lives in `src/ai_client.py`.
|
||||
- See [docs/Readme.md](../docs/Readme.md) for the full **41-guide index** covering context curation, shaders, RAG, Beads, hot reload, personas, NERV theme, workspace profiles, and command palette.
|
||||
- **[docs/guide_architecture.md](../docs/guide_architecture.md):** Thread domains, cross-thread patterns, AI client multi-provider (Gemini, Anthropic, DeepSeek, MiniMax), HITL Execution Clutch.
|
||||
- **[docs/guide_tools.md](../docs/guide_tools.md):** MCP Bridge 3-layer security, full 45-tool inventory, Hook API, ApiHookClient, `/api/ask` HITL protocol.
|
||||
- **[docs/guide_mma.md](../docs/guide_mma.md):** Ticket/Track/WorkerContext data structures, DAG engine, ConductorEngine, Tier 2/3/4 lifecycles, persona application.
|
||||
- **[docs/guide_simulations.md](../docs/guide_simulations.md):** `live_gui` fixture, Puppeteer pattern, mock provider, test areas by subsystem.
|
||||
- **[docs/guide_testing.md](../docs/guide_testing.md):** **NEW** — 251 test files, 5 categories, 7 conftest fixtures (`isolate_workspace`, `reset_paths`, `reset_ai_client`, `vlogger`, `kill_process_tree`, `mock_app`, `live_gui` session-scoped), Puppeteer pattern, mock provider, structural testing contract.
|
||||
- **[docs/guide_gui_2.md](../docs/guide_gui_2.md):** **NEW** — `src/gui_2.py` (~437KB main GUI): App class lifecycle, ~90 module-level render functions, Multi-Viewport docks, panel registry, command palette integration, ImGuiScope context managers, hot reload support.
|
||||
- **[docs/guide_ai_client.md](../docs/guide_ai_client.md):** **NEW** — `src/ai_client.py` (~166KB): multi-provider LLM singleton (8 providers: gemini, anthropic, deepseek, minimax, qwen, grok, llama), async dispatch via `asyncio.gather`, threading.local for source tier tagging, Anthropic ephemeral caching + Gemini explicit caching, Tier 4 QA error interception, inlined `VendorCapabilities` registry (moved from the deleted `src/vendor_capabilities.py`).
|
||||
- **[docs/guide_api_hooks.md](../docs/guide_api_hooks.md):** **NEW** — `src/api_hooks.py` + `src/api_hook_client.py` (~51KB + ~38KB): HookServer on `127.0.0.1:8999`, ApiHookClient wrapper, 8+ endpoints, Remote Confirmation Protocol via `/api/ask`.
|
||||
- **[docs/guide_mcp_client.md](../docs/guide_mcp_client.md):** **NEW** — `src/mcp_client.py` (~92KB, 45 tools; tool specs live in `src/mcp_tool_specs.py`): 3-layer security (Allowlist → Validate → Resolve), all native tools (File I/O, Python AST, C/C++ AST, Analysis, Network, Runtime, Beads), ExternalMCPManager (Stdio + SSE), JSON-RPC 2.0 engine.
|
||||
- **[docs/guide_app_controller.md](../docs/guide_app_controller.md):** **NEW** — `src/app_controller.py` (~240KB): headless orchestrator, AppState dataclass, all subsystem managers, `_predefined_callbacks`/`_gettable_fields` Hook API registries, SyncEventQueue, headless mode.
|
||||
- **[docs/guide_multi_agent_conductor.md](../docs/guide_multi_agent_conductor.md):** **NEW** — `src/multi_agent_conductor.py` + `src/dag_engine.py` (~30KB + ~11KB): TrackDAG (iterative DFS cycle detection, Kahn's topological sort), ExecutionEngine (Auto-Queue / Step Mode), MultiAgentConductor + WorkerPool (concurrency 4), the WorkerPool's internal `run_worker_lifecycle` subprocess template (NOT the deprecated `mma_exec.py`; see `docs/guide_meta_boundary.md`).
|
||||
- **[docs/guide_models.md](../docs/guide_models.md):** **UPDATED 2026-07-02** — `src/models.py` is now a ~1.5KB legacy re-export shim (`Metadata = TrackMetadata` alias + `PROVIDERS` lazy `__getattr__`). Data models moved to per-system files per `module_taxonomy_refactor_20260627`: `src/mma.py` (TrackMetadata, Ticket, Track, WorkerContext), `src/project_files.py` (FileItem), `src/type_aliases.py` (typed boundary + per-aggregate dataclasses), `src/mcp_tool_specs.py` (typed ToolSpec registry, 45 tools), `src/result_types.py` (Result[T], ErrorInfo). `VendorCapabilities` lives in `src/ai_client.py`.
|
||||
- See [docs/Readme.md](../docs/Readme.md) for the full **41-guide index** covering context curation, shaders, RAG, Beads, hot reload, personas, NERV theme, workspace profiles, and command palette.
|
||||
|
||||
## Task Workflow
|
||||
|
||||
@@ -88,146 +88,146 @@ All tasks follow a strict lifecycle:
|
||||
2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
|
||||
|
||||
3. **High-Signal Research Phase:**
|
||||
- **Identify Dependencies:** Use `list_directory`, `get_tree`, and `py_get_imports` to map file relations.
|
||||
- **Map Architecture:** Use `py_get_code_outline` or `py_get_skeleton` on identified files to understand their structure.
|
||||
- **Audit State:** Use `py_get_code_outline` or `py_get_definition` on the target class's `__init__` method to check for existing, unused, or duplicate state variables before adding new ones.
|
||||
- **Analyze Changes:** Use `get_git_diff` if the task involves modifying recently updated code.
|
||||
- **Minimize Token Burn:** Only use `read_file` with `start_line`/`end_line` for specific implementation details once target areas are identified.
|
||||
- **Identify Dependencies:** Use `list_directory`, `get_tree`, and `py_get_imports` to map file relations.
|
||||
- **Map Architecture:** Use `py_get_code_outline` or `py_get_skeleton` on identified files to understand their structure.
|
||||
- **Audit State:** Use `py_get_code_outline` or `py_get_definition` on the target class's `__init__` method to check for existing, unused, or duplicate state variables before adding new ones.
|
||||
- **Analyze Changes:** Use `get_git_diff` if the task involves modifying recently updated code.
|
||||
- **Minimize Token Burn:** Only use `read_file` with `start_line`/`end_line` for specific implementation details once target areas are identified.
|
||||
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.
|
||||
- **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. Add 'Model' and 'Est. Cost' using imgui.table_setup_column(). 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.
|
||||
- **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. Add 'Model' and 'Est. Cost' using imgui.table_setup_column(). 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.
|
||||
- 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.
|
||||
|
||||
7. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
|
||||
```powershell
|
||||
pytest --cov=app --cov-report=html
|
||||
```
|
||||
Target: >80% coverage for new code. The specific tools and commands will vary by language and framework.
|
||||
```powershell
|
||||
pytest --cov=app --cov-report=html
|
||||
```
|
||||
Target: >80% coverage for new code. The specific tools and commands will vary by language and framework.
|
||||
|
||||
8. **Document Deviations:** If implementation differs from tech stack:
|
||||
- **STOP** implementation
|
||||
- Update `tech-stack.md` with new design
|
||||
- Add dated note explaining the change
|
||||
- Resume implementation
|
||||
- **STOP** implementation
|
||||
- Update `tech-stack.md` with new design
|
||||
- Add dated note explaining the change
|
||||
- Resume implementation
|
||||
|
||||
9. **Commit Code Changes:**
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
10. **Attach Task Summary with Git Notes:**
|
||||
- **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
|
||||
- **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change.
|
||||
- **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
|
||||
```powershell
|
||||
# The note content from the previous step is passed via the -m flag.
|
||||
git notes add -m "<note content>" <commit_hash>
|
||||
```
|
||||
- **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
|
||||
- **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change.
|
||||
- **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
|
||||
```powershell
|
||||
# The note content from the previous step is passed via the -m flag.
|
||||
git notes add -m "<note content>" <commit_hash>
|
||||
```
|
||||
|
||||
11. **Get and Record Task Commit SHA:**
|
||||
- **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash.
|
||||
- **Step 10.2: Write Plan:** Write the updated content back to `plan.md`.
|
||||
- **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash.
|
||||
- **Step 10.2: Write Plan:** Write the updated content back to `plan.md`.
|
||||
|
||||
12. **Commit Plan Update:**
|
||||
- **Action:** Stage the modified `plan.md` file.
|
||||
- **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`).
|
||||
- **Action:** Stage the modified `plan.md` file.
|
||||
- **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`).
|
||||
|
||||
### Phase Completion Verification and Checkpointing Protocol
|
||||
|
||||
**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
|
||||
|
||||
1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
|
||||
1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
|
||||
|
||||
2. **Ensure Test Coverage for Phase Changes:**
|
||||
- **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
|
||||
- **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` to get a precise list of all files modified during this phase.
|
||||
- **Step 2.3: Verify and Create Tests:** For each file in the list:
|
||||
- **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`).
|
||||
- For each remaining code file, verify a corresponding test file exists.
|
||||
- If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`).
|
||||
2. **Ensure Test Coverage for Phase Changes:**
|
||||
- **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit.
|
||||
- **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` to get a precise list of all files modified during this phase.
|
||||
- **Step 2.3: Verify and Create Tests:** For each file in the list:
|
||||
- **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`).
|
||||
- For each remaining code file, verify a corresponding test file exists.
|
||||
- If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`).
|
||||
|
||||
3. **Execute Automated Tests in Batches:**
|
||||
- Because the full suite is large (>360 tests) and contains complex UI simulations, running the entire suite frequently can lead to random timeouts or threading access violations.
|
||||
- Before execution, you **must** announce the exact shell command.
|
||||
- **CRITICAL:** When verifying changes, **do not run the full suite (`pytest tests/`)**. Instead, run tests in small, targeted batches (maximum 4 test files at a time). Only use long timeouts (`--timeout=60` or `--timeout=120`) if the specific tests in the batch are known to be slow (e.g., simulation tests).
|
||||
- **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `uv run pytest tests/test_specific_feature.py`"
|
||||
- Execute the announced command.
|
||||
- If tests fail with significant output (e.g., a large traceback), **DO NOT** attempt to read the raw `stderr` directly into your context. Instead, pipe the output to a log file and **spawn a Tier 4 QA Agent via the OpenCode Task tool (`subagent_type: "tier4-qa"`)** with the error output + an explicit instruction "DO NOT fix — provide root cause analysis only". (The legacy `python scripts/mma_exec.py --role tier4-qa` invocation is DEPRECATED; use the OpenCode Task tool.)
|
||||
- You **must** inform the user and begin debugging using the QA Agent's summary. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance.
|
||||
3. **Execute Automated Tests in Batches:**
|
||||
- Because the full suite is large (>360 tests) and contains complex UI simulations, running the entire suite frequently can lead to random timeouts or threading access violations.
|
||||
- Before execution, you **must** announce the exact shell command.
|
||||
- **CRITICAL:** When verifying changes, **do not run the full suite (`pytest tests/`)**. Instead, run tests in small, targeted batches (maximum 4 test files at a time). Only use long timeouts (`--timeout=60` or `--timeout=120`) if the specific tests in the batch are known to be slow (e.g., simulation tests).
|
||||
- **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `uv run pytest tests/test_specific_feature.py`"
|
||||
- Execute the announced command.
|
||||
- If tests fail with significant output (e.g., a large traceback), **DO NOT** attempt to read the raw `stderr` directly into your context. Instead, pipe the output to a log file and **spawn a Tier 4 QA Agent via the OpenCode Task tool (`subagent_type: "tier4-qa"`)** with the error output + an explicit instruction "DO NOT fix — provide root cause analysis only". (The legacy `python scripts/mma_exec.py --role tier4-qa` invocation is DEPRECATED; use the OpenCode Task tool.)
|
||||
- You **must** inform the user and begin debugging using the QA Agent's summary. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance.
|
||||
|
||||
4. **Execute Automated API Hook Verification:**
|
||||
- **CRITICAL:** The Conductor agent will now automatically execute verification tasks using the application's API hooks.
|
||||
- The agent will announce the start of the automated verification to the user.
|
||||
- It will then communicate with the application's IPC server to trigger the necessary verification functions.
|
||||
- **Result Handling:**
|
||||
- All results (successes and failures) from the API hook invocations will be logged.
|
||||
- If all automated verifications pass, the agent will inform the user and proceed to the next step (Create Checkpoint Commit).
|
||||
- If any automated verification fails, the agent will halt the workflow, present the detailed failure logs to the user, and await further instructions for debugging or remediation.
|
||||
4. **Execute Automated API Hook Verification:**
|
||||
- **CRITICAL:** The Conductor agent will now automatically execute verification tasks using the application's API hooks.
|
||||
- The agent will announce the start of the automated verification to the user.
|
||||
- It will then communicate with the application's IPC server to trigger the necessary verification functions.
|
||||
- **Result Handling:**
|
||||
- All results (successes and failures) from the API hook invocations will be logged.
|
||||
- If all automated verifications pass, the agent will inform the user and proceed to the next step (Create Checkpoint Commit).
|
||||
- If any automated verification fails, the agent will halt the workflow, present the detailed failure logs to the user, and await further instructions for debugging or remediation.
|
||||
|
||||
5. **Present Automated Verification Results and User Confirmation:**
|
||||
- After executing automated verification, the Conductor agent will present the results to the user.
|
||||
- If verification passed, the agent will state: "Automated verification completed successfully."
|
||||
- If verification failed, the agent will state: "Automated verification failed. Please review the logs above for details. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance."
|
||||
- **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation from the user to proceed if tests pass, or guidance if tests fail.
|
||||
5. **Present Automated Verification Results and User Confirmation:**
|
||||
- After executing automated verification, the Conductor agent will present the results to the user.
|
||||
- If verification passed, the agent will state: "Automated verification completed successfully."
|
||||
- If verification failed, the agent will state: "Automated verification failed. Please review the logs above for details. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance."
|
||||
- **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation from the user to proceed if tests pass, or guidance if tests fail.
|
||||
|
||||
6. **Create Checkpoint Commit:**
|
||||
- Stage all changes. If no changes occurred in this step, proceed with an empty commit.
|
||||
- Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`).
|
||||
6. **Create Checkpoint Commit:**
|
||||
- Stage all changes. If no changes occurred in this step, proceed with an empty commit.
|
||||
- Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`).
|
||||
|
||||
7. **Attach Auditable Verification Report using Git Notes:**
|
||||
- **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation.
|
||||
- **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit.
|
||||
7. **Attach Auditable Verification Report using Git Notes:**
|
||||
- **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation.
|
||||
- **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit.
|
||||
|
||||
8. **Get and Record Phase Checkpoint SHA:**
|
||||
- **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`).
|
||||
- **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: <sha>]`.
|
||||
- **Step 8.3: Write Plan:** Write the updated content back to `plan.md`.
|
||||
8. **Get and Record Phase Checkpoint SHA:**
|
||||
- **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`).
|
||||
- **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: <sha>]`.
|
||||
- **Step 8.3: Write Plan:** Write the updated content back to `plan.md`.
|
||||
|
||||
9. **Commit Plan Update:**
|
||||
- **Action:** Stage the modified `plan.md` file.
|
||||
- **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
|
||||
- **Action:** Stage the modified `plan.md` file.
|
||||
- **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
|
||||
|
||||
10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note.
|
||||
10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note.
|
||||
|
||||
### Verification via API Hooks
|
||||
|
||||
For features involving the GUI or complex internal state, unit tests are often insufficient. You MUST use the application's built-in API hooks for empirical verification:
|
||||
|
||||
1. **Launch the App with Hooks:** Run the application in a separate shell with the `--enable-test-hooks` flag:
|
||||
```powershell
|
||||
uv run python gui.py --enable-test-hooks
|
||||
```
|
||||
This starts the hook server on port `8999`.
|
||||
1. **Launch the App with Hooks:** Run the application in a separate shell with the `--enable-test-hooks` flag:
|
||||
```powershell
|
||||
uv run python gui.py --enable-test-hooks
|
||||
```
|
||||
This starts the hook server on port `8999`.
|
||||
|
||||
2. **Use the pytest `live_gui` Fixture:** For automated tests, use the session-scoped `live_gui` fixture defined in `tests/conftest.py`. This fixture handles the lifecycle (startup/shutdown) of the application with hooks enabled.
|
||||
```python
|
||||
def test_my_feature(live_gui):
|
||||
# The GUI is now running on port 8999
|
||||
...
|
||||
```
|
||||
Note: pytest must be run with `uv`.
|
||||
2. **Use the pytest `live_gui` Fixture:** For automated tests, use the session-scoped `live_gui` fixture defined in `tests/conftest.py`. This fixture handles the lifecycle (startup/shutdown) of the application with hooks enabled.
|
||||
```python
|
||||
def test_my_feature(live_gui):
|
||||
# The GUI is now running on port 8999
|
||||
...
|
||||
```
|
||||
Note: pytest must be run with `uv`.
|
||||
|
||||
3. **Verify via ApiHookClient:** Use the `ApiHookClient` in `api_hook_client.py` to interact with the running application. It includes robust retry logic and health checks.
|
||||
3. **Verify via ApiHookClient:** Use the `ApiHookClient` in `api_hook_client.py` to interact with the running application. It includes robust retry logic and health checks.
|
||||
|
||||
4. **Verify via REST Commands:** Use PowerShell or `curl` to send commands to the application and verify the response. For example, to check health:
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri "http://127.0.0.1:8999/status" -Method Get
|
||||
```
|
||||
4. **Verify via REST Commands:** Use PowerShell or `curl` to send commands to the application and verify the response. For example, to check health:
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri "http://127.0.0.1:8999/status" -Method Get
|
||||
```
|
||||
|
||||
### Quality Gates
|
||||
|
||||
@@ -275,9 +275,9 @@ Before marking any task complete, verify:
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
### Unit Testing
|
||||
|
||||
@@ -368,14 +368,14 @@ This doc describes **META-TOOLING** — the AI agent orchestration layer used by
|
||||
- **Mandatory Skill Activation:** As the very first step of any MMA-driven process, including track initialization and implementation phases, the agent MUST activate the `mma-orchestrator` skill (`activate_skill mma-orchestrator`) and their corresponding role's specific tier skill. This is crucial for enforcing the 4-Tier token firewall.
|
||||
- **The Sub-Agent Bridge (OpenCode Task tool):** All meta-tooling tiered delegation is now via the OpenCode Task tool with the appropriate `subagent_type`. This is the canonical META-TOOLING mechanism; it replaces the legacy `mma_exec.py` invocation. (The application-domain MMA engine in `src/multi_agent_conductor.py` is unchanged and is documented in `docs/guide_multi_agent_conductor.md`.)
|
||||
- **Model Tiers:**
|
||||
- **Tier 1 (Strategic/Orchestration):** `gemini-3.1-pro-preview`. Focused on product alignment, setup (`/conductor:setup`), and track initialization (`/conductor:newTrack`).
|
||||
- **Tier 2 (Architectural/Tech Lead):** `gemini-3-flash-preview`. Focused on architectural design and track execution (`/conductor:implement`). **Note:** Tier 2 maintains persistent memory throughout a track's implementation.
|
||||
- **Tier 3 (Execution/Worker):** `gemini-2.5-flash-lite`. Used for surgical code implementation and test generation. Operates statelessly (Context Amnesia) but has access to file I/O tools.
|
||||
- **Tier 4 (Utility/QA):** `gemini-2.5-flash-lite`. Used for log summarization and error analysis. Operates statelessly (Context Amnesia) but has access to diagnostic tools.
|
||||
- **Tier 1 (Strategic/Orchestration):** `gemini-3.1-pro-preview`. Focused on product alignment, setup (`/conductor:setup`), and track initialization (`/conductor:newTrack`).
|
||||
- **Tier 2 (Architectural/Tech Lead):** `gemini-3-flash-preview`. Focused on architectural design and track execution (`/conductor:implement`). **Note:** Tier 2 maintains persistent memory throughout a track's implementation.
|
||||
- **Tier 3 (Execution/Worker):** `gemini-2.5-flash-lite`. Used for surgical code implementation and test generation. Operates statelessly (Context Amnesia) but has access to file I/O tools.
|
||||
- **Tier 4 (Utility/QA):** `gemini-2.5-flash-lite`. Used for log summarization and error analysis. Operates statelessly (Context Amnesia) but has access to diagnostic tools.
|
||||
- **Tiered Delegation Protocol (OpenCode Task tool):**
|
||||
- **Tier 3 Worker:** invoke the Task tool with `subagent_type: "tier3-worker"`, providing a surgical prompt with WHERE/WHAT/HOW/SAFETY/COMMIT structure. **DO NOT** use `python scripts/mma_exec.py --role tier3-worker` (deprecated).
|
||||
- **Tier 4 QA Agent:** invoke the Task tool with `subagent_type: "tier4-qa"`, providing the error output + an explicit instruction "DO NOT fix — provide root cause analysis only".
|
||||
- **Tier 1 Orchestrator:** invoke the Task tool with `subagent_type: "tier1-orchestrator"` for track planning tasks.
|
||||
- **Tier 3 Worker:** invoke the Task tool with `subagent_type: "tier3-worker"`, providing a surgical prompt with WHERE/WHAT/HOW/SAFETY/COMMIT structure. **DO NOT** use `python scripts/mma_exec.py --role tier3-worker` (deprecated).
|
||||
- **Tier 4 QA Agent:** invoke the Task tool with `subagent_type: "tier4-qa"`, providing the error output + an explicit instruction "DO NOT fix — provide root cause analysis only".
|
||||
- **Tier 1 Orchestrator:** invoke the Task tool with `subagent_type: "tier1-orchestrator"` for track planning tasks.
|
||||
|
||||
- **MMA Skill Discipline Tests:** The 5 MMA skills (`mma-orchestrator`, `mma-tier1-orchestrator`, `mma-tier2-tech-lead`, `mma-tier3-worker`, `mma-tier4-qa`) at `.agents/skills/mma-*/SKILL.md` are tested for discipline compliance via `tests/test_mma_skill_discipline.py` (per `conductor/tracks/superpowers_review_apply_high_20260705/spec.md` §3.2 and recommendation #2 from `conductor/tracks/superpowers_review_20260619/decisions.md`). The tests are static-analysis of skill documents (text-pattern assertions), not behavioral tests; they run in <5 seconds, require no live_gui or MMA execution, and verify that load-bearing rules are *prominently documented* (not just buried in prose). Future agents extending the MMA skills must also extend the tests.
|
||||
- **Observability:** All hierarchical interactions are recorded in `logs/mma_delegation.log` and detailed sub-agent logs are saved to `logs/agents/`. (These logs are populated by the OpenCode Task tool's logging layer.)
|
||||
@@ -470,14 +470,14 @@ The pattern `push_event(...)` → `time.sleep(N)` → `assert` is a guaranteed r
|
||||
```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
|
||||
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
|
||||
def test_open_modal(live_gui):
|
||||
client.push_event("custom_callback", {"callback": "_toggle_settings", "args": []})
|
||||
assert client.get_value("show_settings_modal"), "settings modal did not open"
|
||||
client.push_event("custom_callback", {"callback": "_toggle_settings", "args": []})
|
||||
assert client.get_value("show_settings_modal"), "settings modal did not open"
|
||||
```
|
||||
|
||||
This pattern surfaced 5+ times in the 2026-06-10 batch-green wave (test_reset_session_clears_mma_and_rag, test_visual_mma, test_visual_sim_gui_ux, test_gui_ux_event_routing, test_z_negative_flows). The fix is always the same: replace `time.sleep` with a poll loop bounded by a retry timeout (typically 5-20 iterations × 0.5s).
|
||||
@@ -497,9 +497,9 @@ This pattern surfaced 5+ times in the 2026-06-10 batch-green wave (test_reset_se
|
||||
|
||||
**How to detect during TDD:**
|
||||
- After modifying a class body, walk the AST and verify all expected methods are class-level:
|
||||
```bash
|
||||
uv run python -c "import ast; tree = ast.parse(open('src/gui_2.py').read()); [print(item.name) for n in ast.walk(tree) if isinstance(n, ast.ClassDef) and n.name == 'App' for item in n.body if isinstance(item, ast.FunctionDef)]"
|
||||
```
|
||||
```bash
|
||||
uv run python -c "import ast; tree = ast.parse(open('src/gui_2.py').read()); [print(item.name) for n in ast.walk(tree) if isinstance(n, ast.ClassDef) and n.name == 'App' for item in n.body if isinstance(item, ast.FunctionDef)]"
|
||||
```
|
||||
- The skeleton via `manual-slop_py_get_skeleton` should show the method as a class member. If it's missing, it's nested.
|
||||
|
||||
**How to fix:** Re-indent the affected method to exactly 2-space class level. Use the file_slice tool or PyCharm-style auto-format to verify. Run the failing test to confirm.
|
||||
@@ -695,42 +695,42 @@ Audit, Goals, Non-Goals, Architecture, Risks, Verification, etc.) with
|
||||
these specific Tier 1 rules:
|
||||
|
||||
- **Current State Audit is MANDATORY** before writing requirements. Read
|
||||
the actual code with MCP tools (`get_file_slice`, `py_get_skeleton`,
|
||||
`py_get_definition`, `py_find_usages`). Document existing
|
||||
implementations with `file:line` references in a "Current State
|
||||
Audit" section. Failure to audit = track failure.
|
||||
the actual code with MCP tools (`get_file_slice`, `py_get_skeleton`,
|
||||
`py_get_definition`, `py_find_usages`). Document existing
|
||||
implementations with `file:line` references in a "Current State
|
||||
Audit" section. Failure to audit = track failure.
|
||||
- **Frame requirements as GAPS, not features.** "The existing X
|
||||
(file.py:L100-200) has Y; this track fills the gap" — not "Build
|
||||
feature Z".
|
||||
(file.py:L100-200) has Y; this track fills the gap" — not "Build
|
||||
feature Z".
|
||||
- **Write worker-ready tasks** in the plan. Each plan task must be
|
||||
executable by a Tier 3 worker. The Tier 1 does NOT execute the
|
||||
plan; the Tier 1 writes it for a Tier 3 to execute.
|
||||
executable by a Tier 3 worker. The Tier 1 does NOT execute the
|
||||
plan; the Tier 1 writes it for a Tier 3 to execute.
|
||||
- **Reference architecture docs** (`docs/guide_*.md`,
|
||||
`conductor/code_styleguides/*.md`) in every spec. Every requirement
|
||||
must point to the existing pattern it follows (or the new pattern it
|
||||
establishes).
|
||||
`conductor/code_styleguides/*.md`) in every spec. Every requirement
|
||||
must point to the existing pattern it follows (or the new pattern it
|
||||
establishes).
|
||||
- **For bug fix tracks: Root Cause Analysis** is mandatory. Read the
|
||||
code, trace the data flow, list specific root cause candidates.
|
||||
Don't ship "I tried X, the test still failed, here's a 200-line
|
||||
report".
|
||||
code, trace the data flow, list specific root cause candidates.
|
||||
Don't ship "I tried X, the test still failed, here's a 200-line
|
||||
report".
|
||||
|
||||
### 3. Metadata format
|
||||
|
||||
The `metadata.json` follows the standard schema. Specific Tier 1 rules:
|
||||
|
||||
- `scope.new_files` / `scope.modified_files` / `scope.deleted_files`
|
||||
are the file-level scope. No "lines of code changed" estimates.
|
||||
are the file-level scope. No "lines of code changed" estimates.
|
||||
- `regressions_and_pre_existing_failures` is a list, not a count.
|
||||
- `pre_existing_failures_remaining` MUST be `[]` for the track to be
|
||||
marked complete.
|
||||
marked complete.
|
||||
- `deferred_to_followup_tracks` is a list of followup items with
|
||||
title + description + track_status. No "estimated effort".
|
||||
title + description + track_status. No "estimated effort".
|
||||
- `estimated_effort` field uses `method: "scope (per workflow.md §Tier
|
||||
1 Track Initialization Rules). NO day estimates."` and a per-phase
|
||||
`scope` summary (e.g., `phase_1: "1 task: investigation"`).
|
||||
1 Track Initialization Rules). NO day estimates."` and a per-phase
|
||||
`scope` summary (e.g., `phase_1: "1 task: investigation"`).
|
||||
- `risk_register` entries use scope-relative likelihood ("medium"
|
||||
means "the implementation may be larger than the spec suggests"),
|
||||
not time-relative ("takes longer than 2 days").
|
||||
means "the implementation may be larger than the spec suggests"),
|
||||
not time-relative ("takes longer than 2 days").
|
||||
|
||||
### 4. Plan format
|
||||
|
||||
@@ -738,11 +738,11 @@ The `plan.md` follows the standard TDD red-first template. Specific
|
||||
Tier 1 rules:
|
||||
|
||||
- Each task has WHERE / WHAT / HOW / SAFETY / COMMIT / GIT NOTE
|
||||
fields. Tasks are NOT grouped by "day" or "hour".
|
||||
fields. Tasks are NOT grouped by "day" or "hour".
|
||||
- Phase headers describe the WORK, not the TIME. ("Phase 1:
|
||||
Investigation" not "Phase 1: Day 1").
|
||||
Investigation" not "Phase 1: Day 1").
|
||||
- The plan is read by a Tier 3 worker; the Tier 1 never executes it
|
||||
themselves.
|
||||
themselves.
|
||||
|
||||
### 5. The "Reasonable effort" guard
|
||||
|
||||
@@ -770,8 +770,8 @@ Every track's `conductor/tracks/<track_id>/state.toml` should follow this struct
|
||||
[meta]
|
||||
track_id = "<track_id>"
|
||||
name = "<Human-Readable Name>"
|
||||
status = "active" # active | completed
|
||||
current_phase = 0 # 0 = pre-Phase 1; 1..N = in Phase N; "complete" if all phases done
|
||||
status = "active" # active | completed
|
||||
current_phase = 0 # 0 = pre-Phase 1; 1..N = in Phase N; "complete" if all phases done
|
||||
last_updated = "<YYYY-MM-DD>"
|
||||
|
||||
[blocked_by]
|
||||
@@ -818,9 +818,9 @@ When the implementing agent encounters a decision not covered by the plan:
|
||||
|
||||
1. **If the decision is purely cosmetic** (e.g., variable naming, comment placement, exact spacing): pick the option that matches the surrounding code style. Document the choice in the commit message.
|
||||
2. **If the decision affects the architecture** (e.g., the spec's data model doesn't fit the code; the plan's approach doesn't compile; an external library doesn't behave as expected): **STOP. Do not commit. Report to the Tier 2 Tech Lead.** The lead will either:
|
||||
- Update the spec to match the new constraint
|
||||
- Add a clarifying task to the plan
|
||||
- Defer the work to a follow-up track
|
||||
- Update the spec to match the new constraint
|
||||
- Add a clarifying task to the plan
|
||||
- Defer the work to a follow-up track
|
||||
3. **If the decision is a regression** (e.g., the plan's code works but introduces a known bug, or fails a test the plan didn't anticipate): **STOP and report.** Don't ship a known regression to save time. The lead will decide whether to fix forward or roll back.
|
||||
|
||||
**The principle: small decisions, decide yourself. Large decisions, escalate.** The boundary is "does this decision require a new spec or plan update?"
|
||||
@@ -913,20 +913,20 @@ This section extends the existing workflow with the patterns surfaced by the `na
|
||||
|
||||
```
|
||||
- [ ] tests/test_knowledge_store.py: 5+ tests for the 7-category schema
|
||||
- [ ] parse_harvest_json: 7 categories; rows must be lists
|
||||
- [ ] parse_harvest_json: rejects prose
|
||||
- [ ] parse_harvest_json: tolerates ```json ... ``` code-fence
|
||||
- [ ] parse_harvest_json: rejects non-dict payloads
|
||||
- [ ] regenerate_digest: 4KB cap; truncation with note
|
||||
- [ ] parse_harvest_json: 7 categories; rows must be lists
|
||||
- [ ] parse_harvest_json: rejects prose
|
||||
- [ ] parse_harvest_json: tolerates ```json ... ``` code-fence
|
||||
- [ ] parse_harvest_json: rejects non-dict payloads
|
||||
- [ ] regenerate_digest: 4KB cap; truncation with note
|
||||
- [ ] tests/test_knowledge_harvest.py: 8+ tests for the pipeline
|
||||
- [ ] classify (live/user-kept/prune/harvest/keep)
|
||||
- [ ] merge_harvest per category
|
||||
- [ ] per-file knowledge: existing-file branch
|
||||
- [ ] per-file knowledge: missing-file branch
|
||||
- [ ] ledger dedup (sha256-of-content)
|
||||
- [ ] retry budget (2 attempts)
|
||||
- [ ] "too-large" budget guard (1MB)
|
||||
- [ ] "delete to turn off" regeneration
|
||||
- [ ] classify (live/user-kept/prune/harvest/keep)
|
||||
- [ ] merge_harvest per category
|
||||
- [ ] per-file knowledge: existing-file branch
|
||||
- [ ] per-file knowledge: missing-file branch
|
||||
- [ ] ledger dedup (sha256-of-content)
|
||||
- [ ] retry budget (2 attempts)
|
||||
- [ ] "too-large" budget guard (1MB)
|
||||
- [ ] "delete to turn off" regeneration
|
||||
```
|
||||
|
||||
### The cache ordering TDD protocol
|
||||
@@ -935,17 +935,17 @@ This section extends the existing workflow with the patterns surfaced by the `na
|
||||
|
||||
```
|
||||
- [ ] tests/test_aggregate_caching.py: the byte-comparison test
|
||||
- [ ] first N chars are identical across turns of the same discussion
|
||||
- [ ] N = aggregate.stable_prefix_length(ctrl)
|
||||
- [ ] failure modes: new layer in wrong position, volatile input leak
|
||||
- [ ] first N chars are identical across turns of the same discussion
|
||||
- [ ] N = aggregate.stable_prefix_length(ctrl)
|
||||
- [ ] failure modes: new layer in wrong position, volatile input leak
|
||||
- [ ] tests/test_cache_state.py: 3+ tests for the cache state machine
|
||||
- [ ] per-provider TTL defaults
|
||||
- [ ] DiscussionCacheState lifecycle
|
||||
- [ ] invalidate + regeneration
|
||||
- [ ] per-provider TTL defaults
|
||||
- [ ] DiscussionCacheState lifecycle
|
||||
- [ ] invalidate + regeneration
|
||||
- [ ] tests/test_gui_caching.py: 3+ live_gui tests for the "Caching" panel
|
||||
- [ ] panel renders provider summaries
|
||||
- [ ] invalidate button
|
||||
- [ ] per-discussion disable/enable
|
||||
- [ ] panel renders provider summaries
|
||||
- [ ] invalidate button
|
||||
- [ ] per-discussion disable/enable
|
||||
```
|
||||
|
||||
### The compaction TDD protocol
|
||||
@@ -954,16 +954,16 @@ This section extends the existing workflow with the patterns surfaced by the `na
|
||||
|
||||
```
|
||||
- [ ] tests/test_run_discussion_compaction.py: 10+ tests
|
||||
- [ ] compact preserves decisions
|
||||
- [ ] compact preserves constraints
|
||||
- [ ] compact preserves failures
|
||||
- [ ] compact preserves artifact refs
|
||||
- [ ] compact removes duplicates
|
||||
- [ ] compact replaces chronology with state
|
||||
- [ ] compact is substantially smaller
|
||||
- [ ] compact preserves capability
|
||||
- [ ] compact returns 12-section structure
|
||||
- [ ] compact continues until self-review passes
|
||||
- [ ] compact preserves decisions
|
||||
- [ ] compact preserves constraints
|
||||
- [ ] compact preserves failures
|
||||
- [ ] compact preserves artifact refs
|
||||
- [ ] compact removes duplicates
|
||||
- [ ] compact replaces chronology with state
|
||||
- [ ] compact is substantially smaller
|
||||
- [ ] compact preserves capability
|
||||
- [ ] compact returns 12-section structure
|
||||
- [ ] compact continues until self-review passes
|
||||
```
|
||||
|
||||
### The RAG discipline TDD protocol
|
||||
@@ -972,10 +972,10 @@ This section extends the existing workflow with the patterns surfaced by the `na
|
||||
|
||||
```
|
||||
- [ ] tests/test_rag_discipline.py: 4+ tests
|
||||
- [ ] RAG disabled: no {rag-context} block
|
||||
- [ ] RAG results have provenance (file path + chunk)
|
||||
- [ ] RAG results do not mutate disc_entries
|
||||
- [ ] RAG failure returns empty (graceful)
|
||||
- [ ] RAG disabled: no {rag-context} block
|
||||
- [ ] RAG results have provenance (file path + chunk)
|
||||
- [ ] RAG results do not mutate disc_entries
|
||||
- [ ] RAG failure returns empty (graceful)
|
||||
```
|
||||
|
||||
See `conductor/code_styleguides/knowledge_artifacts.md`, `cache_friendly_context.md`, `rag_integration_discipline.md` for the canonical styleguides.
|
||||
|
||||
Reference in New Issue
Block a user