Refactor: Add maintenance report and implementation plan (journal updated).

Author: apiad

.gemini/agents/planner.md

@@ -13,13 +13,14 @@ max_turns: 15
 You are an expert software architect and strategic planner. Your sole mission is to analyze the codebase and produce a comprehensive execution plan for a specific objective.
 
 **Mandates:**
-1. **Read-Only Mode:** You MUST NOT modify, create, or delete any files in the repository. Use your search and read tools strictly for investigation.
-2. **Deep Context:** Investigate the existing architecture, file structure, and relevant dependencies before proposing any changes.
-3. **Actionable Output:** Your final output must be a highly detailed, step-by-step Markdown plan. It should include:
+1. **Strictly Read-Only:** You MUST NOT modify, create, or delete any files in the repository. You do not have access to write tools. Use your search and read tools strictly for investigation.
+2. **Analysis-to-Return Workflow:** Your role is to generate the plan and return it as your final response. You DO NOT save the plan to a file; the orchestrating command will handle persistence.
+3. **Deep Context:** Investigate the existing architecture, file structure, and relevant dependencies before proposing any changes.
+4. **Actionable Output:** Your final output must be a highly detailed, step-by-step Markdown plan. It should include:
    - **Objective:** A clear summary of the goal.
    - **Architectural Impact:** High-level overview of how the change fits into the existing system.
    - **File Operations:** Explicitly list which files need to be modified, created, or deleted.
    - **Step-by-Step Execution:** A logical sequence of tasks (e.g., Step 1: Update API, Step 2: Implement UI, Step 3: Add Tests).
    - **Testing Strategy:** How to validate the changes.
 
-When given an objective, thoroughly investigate the codebase and return the final Markdown plan.
+When given an objective, thoroughly investigate the codebase and return the final Markdown plan content.

.gemini/commands/plan.toml

@@ -11,16 +11,18 @@ Follow these phases strictly:
 1. Do not start planning immediately. Analyze the user's initial request.
 2. If the request is vague or lacks specific technical details, use `ask_user` to ask 1-3 targeted, follow-up questions to gather necessary context. (e.g., "Are we targeting a specific UI component?", "Should this include database migrations?").
 
-### Phase 2: Agentic Analysis
+### Phase 2: Agentic Analysis (Planner)
 1. Once you have a clear understanding of the objective, invoke the `planner` subagent.
-2. Pass the fully clarified objective to the `planner`. The `planner` will scan the repository and return a detailed Markdown plan.
-3. Review the plan with the user, and apply necessary corrections or adjustments based on their feedback. Use `ask_user` to confirm any changes.
-4. Ensure the final plan is comprehensive, actionable, and aligned with the user's goals before proceeding to the next phase.
-
-### Phase 3: Saving the Plan
-1. Ensure the `plans/` directory exists.
-2. Take the Markdown plan generated by the `planner` agent and save it to a new file in the `plans/` directory. Use a descriptive, kebab-case filename (e.g., `plans/implement-auth.md`).
-3. Notify the user that the plan has been saved.
+2. **Analysis-to-Content Workflow:** Instruct the `planner` to scan the repository and return a detailed Markdown plan.
+3. **Wait for Content:** Ensure the `planner` returns the full Markdown content of the plan.
+4. Review the plan with the user, and apply necessary corrections or adjustments based on their feedback. Use `ask_user` to confirm any changes.
+
+### Phase 3: Persistence (Saving the Plan)
+1. **Command Responsibility:** As the orchestrating command, YOU are responsible for saving the plan. The `planner` agent is read-only.
+2. Ensure the `plans/` directory exists.
+3. Take the Markdown plan generated by the `planner` agent and save it to a new file in the `plans/` directory using `write_file`.
+4. Use a descriptive, kebab-case filename (e.g., `plans/implement-auth.md`).
+5. Notify the user that the plan has been saved.
 
 ### Phase 4: Task Synchronization (TASKS.md)
 1. Read the current `TASKS.md` file to understand the project roadmap.

TASKS.md

@@ -18,6 +18,8 @@ Put done tasks into the Archive.
 
 ## Active Tasks
 
+- [ ] Implement documentation harmonization and refactor tests for dynamic synchronization. (See plan: plans/maintenance-improvements.md)
+
 ---
 
 ## Archive

journal/2026-03-23.md

@@ -11,3 +11,4 @@
 [2026-03-23T06:07:18] - Align README, Style Guide, Docs, and historical entries with writer/reviewer naming.
 [2026-03-23T06:08:20] - Archive completed /draft command and writer agent improvement task.
 [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.

plans/maintenance-improvements.md

@@ -0,0 +1,88 @@
+# Execution Plan: Documentation and Test Synchronization
+
+## Objective
+Harmonize the project's documentation with its implementation by standardizing command names, filling documentation gaps, and replacing brittle tests with a dynamic synchronization verification suite.
+
+## Architectural Impact
+- **Consistency:** Ensures that users and AI agents have a single, accurate source of truth for command names and capabilities.
+- **Maintainability:** Reduces test suite fragility by moving from hard-coded string matching to dynamic discovery.
+- **Safety:** Strengthens the link between implementation (TOML/Markdown) and documentation (README/User Guide) through automated CI checks.
+
+## File Operations
+
+### Files to Modify:
+- `README.md`: Update `/learn` description; ensure `/document` is correctly referenced.
+- `docs/index.md`: Rename `/docs` references to `/document`.
+- `docs/user-guide.md`:
+    - Rename `/docs` to `/document`.
+    - Add missing `/scaffold` and `/onboard` sections.
+    - Remove redundant `/learn` section.
+    - Explicitly identify `learner` and `debugger` as subagents.
+- `tests/test_review_command.py`: Refactor to remove brittle string assertions.
+
+### Files to Create:
+- `tests/test_sync.py`: New dynamic test suite for implementation-documentation synchronization.
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1: Documentation Harmonization
+
+#### Step 1.1: Update `docs/index.md`
+- Replace the legacy `/docs` command reference with `/document` in the "Key Capabilities" section.
+
+#### Step 1.2: Update `docs/user-guide.md`
+- **Search & Replace:** Globally replace `/docs` with `/document`.
+- **Deduplication:** Remove the second, redundant occurrence of the `### /learn` section.
+- **Explicit Agent Identification:**
+    - Update the `/learn` section to explicitly mention the `learner` subagent.
+    - Update the `/debug` section to explicitly mention the `debugger` subagent.
+- **Add Missing Commands:**
+    - Add a `### /onboard` section under "The Discovery & Strategy Workflow".
+    - Add a `### /scaffold` section under "The Software Development Workflow".
+
+#### Step 1.3: Update `README.md`
+- Update the `/learn` section under "Phase 1: Planning & Discovery" to explicitly mention the `learner` subagent (consistent with how `/debug` and `/plan` are described).
+
+---
+
+### Phase 2: Test Suite Refactoring
+
+#### Step 2.1: Refactor `tests/test_review_command.py`
+- Modify `test_reviewer_agent_has_grep_search` to verify file existence and basic Markdown structure (e.g., presence of a title) instead of specific tool names like `grep_search`.
+- Modify `test_review_command_is_multiphase` to verify the TOML file contains `description` and `prompt` keys, rather than searching for specific "Phase X" strings.
+- Simplify `test_maintenance_command_is_audit` and `test_planner_agent_read_only` to focus on existence and high-level role rather than internal implementation details.
+- Retain "gone" file checks (e.g., `test_editor_agent_gone`) as they validate successful migrations.
+
+---
+
+### Phase 3: Dynamic Synchronization Implementation
+
+#### Step 3.1: Create `tests/test_sync.py`
+Implement a pytest-compatible script that performs the following:
+1.  **Command Discovery:** Programmatically list all `.toml` files in `.gemini/commands/`.
+2.  **Agent Discovery:** Programmatically list all `.md` files in `.gemini/agents/`.
+3.  **Forward Sync Check:**
+    - Verify every discovered command is mentioned as `/{command}` in both `README.md` and `docs/user-guide.md`.
+    - Verify every discovered agent is mentioned in `docs/design.md` and `docs/user-guide.md`.
+4.  **Reverse Sync Check:**
+    - Parse `README.md` and `docs/user-guide.md` for any strings matching the `/{command}` pattern.
+    - Assert that each found pattern (excluding known exceptions like `/docs`) has a corresponding `.toml` file in `.gemini/commands/`.
+5.  **Agent Role Verification:**
+    - Ensure `README.md` and `docs/user-guide.md` use the terms "agent" or "subagent" when describing the specialized roles (e.g., `planner`, `researcher`, `learner`).
+
+---
+
+## Testing Strategy
+
+### 1. Manual Validation
+- Inspect the modified `docs/user-guide.md` and `README.md` to ensure formatting is correct and descriptions are accurate.
+- Verify that the `/document` command is used consistently across all files.
+
+### 2. Automated Validation
+- **Run the refactored suite:** Execute `pytest tests/test_review_command.py` to ensure the new, leaner assertions pass.
+- **Run the synchronization suite:** Execute `pytest tests/test_sync.py`. This test is expected to fail initially if any commands were missed during the manual update phase, providing an automated "punch list" for completion.
+
+### 3. CI/CD Integration
+- Ensure these new tests are picked up by the `make test` target, which is triggered by the `pre-commit.py` hook and GitHub Actions.

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

@@ -0,0 +1,65 @@
+# Maintenance Report Card - 2026-03-23
+
+## Executive Summary
+This audit focused on the synchronization between implementation (commands and agents) and documentation (README and user guides), as well as the robustness of the test suite. While the core functionality is well-documented, there are notable inconsistencies in command naming and coverage across different documentation files. Additionally, the current test suite is overly brittle due to specific content matching.
+
+---
+
+## 🛠️ Command & Agent Inventory
+
+### Commands (.gemini/commands/) - 15 Total
+- `commit`, `cron`, `debug`, `document`, `draft`, `issues`, `learn`, `maintenance`, `onboard`, `plan`, `release`, `research`, `review`, `scaffold`, `task`.
+
+### Agents (.gemini/agents/) - 6 Total
+- `debugger`, `learner`, `planner`, `researcher`, `reviewer`, `writer`.
+
+---
+
+## 🔍 Synchronization Audit
+
+### 1. Naming Inconsistencies
+- **Critical Issue:** The command defined in `.gemini/commands/document.toml` is correctly referred to as `/document` in `README.md`, but incorrectly as `/docs` in `docs/index.md` and `docs/user-guide.md`.
+- **Impact:** Users following the documentation will encounter errors if they attempt to run `/docs`.
+
+### 2. Documentation Coverage Gaps
+- **README.md:** Comprehensive. Mentions all 15 commands.
+- **docs/user-guide.md:**
+    - **Missing Commands:** `/scaffold`, `/onboard`.
+    - **Naming Error:** Uses `/docs` instead of `/document`.
+- **docs/index.md:**
+    - **Naming Error:** Uses `/docs` instead of `/document`.
+
+### 3. Agent Mentions
+- Agents are generally well-represented, but `learner` and `debugger` are sometimes mentioned only through their respective commands (`/learn`, `/debug`) rather than being explicitly identified as subagents in all documentation sections.
+
+---
+
+## 🧪 Test Suite Analysis
+
+### Observations on `tests/test_review_command.py`
+The current tests are **overly strict** and prone to failure when the implementation details change. Specifically:
+- `test_reviewer_agent_has_grep_search`: Asserts exact string `"grep_search"` in `reviewer.md`.
+- `test_review_command_is_multiphase`: Asserts exact strings `"Phase 1"`, `"Phase 2"`, etc.
+- `test_maintenance_command_is_audit`: Asserts exact output strings and internal agent names.
+- `test_planner_agent_read_only`: Asserts lack of `"write_file"` and `"replace"` strings.
+
+### Actionable Suggestion for Tests
+Refactor the tests to be **dynamic and behavior-oriented**:
+1.  **Dynamic Discovery:** Iterate through `.gemini/commands/*.toml` and `.gemini/agents/*.md`.
+2.  **Sync Verification:** Ensure every command file found has a corresponding entry in `README.md` and `docs/user-guide.md`.
+3.  **Reverse Sync:** Ensure every command mentioned in `docs/*.md` exists in `.gemini/commands/`.
+4.  **Generic Validation:** Check for TOML validity and basic structure rather than specific wording.
+
+---
+
+## 📝 Actionable Recommendations
+
+1.  **Standardize Command Names:** Rename `document.toml` to `docs.toml` OR update all documentation to use `/document`. (Recommendation: Rename to `docs.toml` for brevity and alignment with user expectations).
+2.  **Harmonize Documentation:** Update `docs/user-guide.md` to include missing commands (`/scaffold`, `/onboard`) and fix the `/docs` vs `/document` discrepancy.
+3.  **Refactor Tests:** Implement a new test file (e.g., `tests/test_sync.py`) that programmatically verifies the 1:1 mapping between implementation and documentation.
+4.  **Leaner Assertions:** Remove specific content assertions from `tests/test_review_command.py` to prevent unnecessary maintenance overhead.
+
+---
+
+## 💡 Orchestration Tip
+Use the `/plan` command, pointing to this report, to formulate a safe strategy for standardizing command names and refactoring the test suite to ensure long-term maintainability.

tests/test_review_command.py

@@ -70,24 +70,56 @@ def test_maintenance_command_is_audit():
     # Ensure it doesn't mention Step-by-Step Implementation or modification
     assert "Step-by-Step Implementation" not in content
 
+def test_planner_agent_read_only():
+    with open(".gemini/agents/planner.md", "r") as f:
+        content = f.read()
+    assert "planner" in content.lower()
+    assert "read-only" in content.lower()
+
+def test_plan_command_persistence_responsibility():
+    with open(".gemini/commands/plan.toml", "r") as f:
+        content = f.read()
+    assert "Command Responsibility" in content
+    assert "responsible for saving the plan" in content.lower()
+    assert "planner" in content.lower()
+    assert "agent" in content.lower()
+    assert "read-only" in content.lower()
+
 if __name__ == "__main__":
     # Simple manual runner for now
     try:
+        print("Checking reviewer agent exists...")
         test_reviewer_agent_exists()
+        print("Checking editor agent gone...")
         test_editor_agent_gone()
+        print("Checking review command exists...")
         test_review_command_exists()
+        print("Checking revise command gone...")
         test_revise_command_gone()
+        print("Checking reviewer agent has grep_search...")
         test_reviewer_agent_has_grep_search()
+        print("Checking review command is multi-phase...")
         test_review_command_is_multiphase()
+        print("Checking draft command suggests review...")
         test_draft_command_suggests_review()
+        print("Checking docs updated...")
         test_docs_updated()
 
+        print("Checking writer agent exists...")
         test_writer_agent_exists()
+        print("Checking reporter agent gone...")
         test_reporter_agent_gone()
+        print("Checking writer agent has replace...")
         test_writer_agent_has_replace()
+        print("Checking draft command is multi-mode...")
         test_draft_command_is_multimode()
 
+        print("Checking maintenance command is audit...")
         test_maintenance_command_is_audit()
+        print("Checking planner agent is read-only...")
+        test_planner_agent_read_only()
+        print("Checking plan command persistence responsibility...")
+        test_plan_command_persistence_responsibility()
 
         print("Tests Passed")
     except AssertionError as e: