Refactor: Add maintenance report v2 and implementation plan.

Author: apiad

TASKS.md

@@ -18,12 +18,14 @@ Put done tasks into the Archive.
 
 ## Active Tasks
 
-- [/] Implement documentation harmonization and refactor tests for dynamic synchronization. (@apiad) (See plan: plans/maintenance-improvements.md)
+- [ ] Implement dynamic structural testing suite and finalize documentation sync. (See plan: plans/implement-maintenance-v2.md)
 
 ---
 
 ## Archive
 
+- [x] Implement documentation harmonization and refactor tests for dynamic synchronization. (2026-03-23) (See plan: plans/maintenance-improvements.md)
+
 - [x] Improve the `/draft` command and evolve the `writer` agent to include a review-driven "Refinement Phase." (2026-03-23) (See plan: plans/improve-draft-command-and-writer-agent.md)
 
 - [x] Improve the `/review` command and evolve the `reviewer` agent to a non-destructive, multi-phase audit workflow. (2026-03-23) (See plan: plans/improve-review-command.md)

journal/2026-03-23.md

@@ -13,3 +13,4 @@
 [2026-03-23T06:50:29] - Refactor /maintenance command into a read-only audit workflow using codebase_investigator.
 [2026-03-23T07:10:07] - Perform maintenance audit and generate implementation plan for documentation harmonization.
 [2026-03-23T07:14:22] - Harmonize documentation, refactor tests with dynamic sync, and integrate uv/pytest.
+[2026-03-23T07:22:14] - Commit maintenance v2 plan and research before starting work.

plans/implement-maintenance-v2.md

@@ -0,0 +1,44 @@
+# Implementation Plan: Dynamic Structural Testing and Documentation Sync
+
+## 1. Objective
+This plan addresses the gaps identified in `research/maintainance-report-2026-03-23-v2.md`. It implements a scalable, dynamic testing strategy for all commands and agents, refactors brittle legacy tests to focus on migration integrity, and ensures full documentation synchronization for the `/scaffold` and `/onboard` commands.
+
+## 2. Architectural Impact
+- **Dynamic Validation:** Replaces hardcoded individual tests with a discovery-based suite (`tests/test_structure.py`) that automatically covers new commands/agents.
+- **Maintenance Efficiency:** Reduces test code volume by removing redundant structural checks from specialized test files.
+- **Documentation Integrity:** Enforces a 1:1 mapping between available commands and the User Guide, eliminating brittle "skip lists" in the synchronization tests.
+
+## 3. File Operations
+
+| Action | File Path | Description |
+| :--- | :--- | :--- |
+| **Create** | `tests/test_structure.py` | New test file using `pytest.mark.parametrize` for blanket coverage. |
+| **Modify** | `tests/test_review_command.py` | Cleanup of structural/content assertions; retain migration checks. |
+| **Modify** | `docs/user-guide.md` | Add/Update documentation for `/scaffold` and `/onboard`. |
+| **Modify** | `tests/test_sync.py` | Remove hardcoded skips for `scaffold` and `onboard`. |
+
+## 4. Step-by-Step Execution
+
+### Step 1: Implement Dynamic Structural Testing
+Create `tests/test_structure.py` with the following requirements:
+- **Command Discovery:** Use `os.listdir(".gemini/commands/")` to find all `.toml` files.
+- **Command Logic:** Verify each command is valid TOML and has non-empty `description` and `prompt` strings.
+- **Agent Discovery:** Use `os.listdir(".gemini/agents/")` to find all `.md` files.
+- **Agent Logic:** Verify each agent is valid Markdown and contains the agent's name (filename without extension) in the content.
+
+### Step 2: Refactor `tests/test_review_command.py`
+- **Delete:** `test_reviewer_agent_exists`, `test_review_command_exists`, `test_reviewer_agent_is_valid_markdown`, `test_review_command_is_valid_toml`, `test_maintenance_command_is_audit`, `test_planner_agent_read_only`, `test_writer_agent_exists`, `test_draft_command_is_multimode`.
+- **Retain:** `test_editor_agent_gone`, `test_revise_command_gone`, `test_reporter_agent_gone` to ensure migration state persists.
+
+### Step 3: Documentation Sync
+- **Update `docs/user-guide.md`**: Ensure the `/scaffold` and `/onboard` sections have consistent "How it works" and "Why it works" formatting.
+- **Update `tests/test_sync.py`**: Remove the exclusion list in `test_commands_synced_in_user_guide` so that `scaffold` and `onboard` are strictly checked for documentation presence.
+
+### Step 4: Final Validation
+- Run the full test suite using `make test`.
+- Verify the total number of tests in `test_structure.py` matches the number of files in `.gemini/commands/` (15) and `.gemini/agents/` (6).
+
+## 5. Testing Strategy
+1. **Dynamic discovery check:** Add a dummy command `temp_test.toml` and verify `make test` automatically picks it up and fails (due to lack of content).
+2. **Sync check:** Temporarily remove `/scaffold` from `docs/user-guide.md` and verify `tests/test_sync.py` fails.
+3. **Migration check:** Ensure `tests/test_review_command.py` passes, confirming legacy files have not been reintroduced.

research/maintainance-report-2026-03-23-v2.md

@@ -0,0 +1,60 @@
+# Maintenance Report Card - 2026-03-23 (v2)
+
+## Executive Summary
+This second audit focused on the **lenient structural testing** of all commands and agents. While the initial synchronization tests (`tests/test_sync.py`) were a significant improvement, many commands and agents still lack basic structural verification. Furthermore, some tests remain brittle by asserting on specific prompt content.
+
+---
+
+## 🛠️ Testing Inventory & Gaps
+
+### Commands (.gemini/commands/) - 15 Total
+- **Covered (5):** `review`, `maintenance`, `draft`, `plan`, `document`. (Through `test_review_command.py` and `test_sync.py`)
+- **Missing (10):** `commit`, `cron`, `debug`, `issues`, `learn`, `onboard`, `release`, `research`, `scaffold`, `task`.
+- **Gaps:** No basic TOML validity or key presence (`description`, `prompt`) checks for these commands.
+
+### Agents (.gemini/agents/) - 6 Total
+- **Covered (3):** `reviewer`, `planner`, `writer`. (Through `test_review_command.py`)
+- **Missing (3):** `debugger`, `learner`, `researcher`.
+- **Gaps:** No basic Markdown structure (e.g., presence of a title or specific name in frontmatter) checks for these agents.
+
+---
+
+## 🔍 Synchronization Issues
+
+### 1. Brittle Documentation Skips
+- **Issue:** `tests/test_sync.py` contains hardcoded skips for `scaffold` and `onboard` regarding their presence in `docs/user-guide.md`.
+- **Impact:** If these commands are ever removed or renamed, the tests won't catch it. The documentation should be updated, and the skips removed.
+
+### 2. Brittle Content Matching
+- **Issue:** `tests/test_review_command.py` still checks for specific strings like `"codebase_investigator"` or `"Maintenance Report Card"`.
+- **Impact:** Small wording changes in the prompts will break the tests unnecessarily.
+
+---
+
+## 📝 Actionable Recommendations
+
+### 1. Unified Dynamic Testing Strategy
+Implement a new test file, `tests/test_structure.py`, that uses `pytest.mark.parametrize` to dynamically discover and test all files in `.gemini/commands/` and `.gemini/agents/`.
+
+#### **Command Requirements (Lenient):**
+- Must be valid TOML.
+- Must contain `description` (string) and `prompt` (string) keys.
+- Prompt must not be empty.
+
+#### **Agent Requirements (Lenient):**
+- Must be valid Markdown.
+- Must contain the agent's name (case-insensitive) in the content or as a header.
+- Should contain a `tools` section (if relevant to the framework's schema).
+
+### 2. Cleanup `tests/test_review_command.py`
+- Move generalized structural tests to the new dynamic suite.
+- Keep only migration-specific tests (e.g., checking that `editor.md` or `revise.toml` no longer exist).
+
+### 3. Finalize Documentation Sync
+- Ensure `scaffold` and `onboard` are fully documented in `docs/user-guide.md`.
+- Remove the hardcoded skips from `tests/test_sync.py`.
+
+---
+
+## 💡 Orchestration Tip
+Use the `/plan` command, pointing to this report, to formulate a strategy for implementing `tests/test_structure.py`. This will provide "blanket" coverage for all current and future commands/agents with minimal maintenance overhead.