docs(core): document procedural task management and tier protocol

Author: apiad

.gemini/settings.json

@@ -9,6 +9,22 @@
           "model": "gemini-3.1-pro-preview"
         }
       },
+      {
+        "match": {
+          "overrideScope": "debugger"
+        },
+        "modelConfig": {
+          "model": "gemini-3.1-pro-preview"
+        }
+      },
+      {
+        "match": {
+          "overrideScope": "learner"
+        },
+        "modelConfig": {
+          "model": "gemini-3.1-pro-preview"
+        }
+      },
       {
         "match": {
           "overrideScope": "reviewer"

docs/design.md

@@ -34,6 +34,12 @@ Helper scripts that standardize framework operations across different environmen
 
 Commands define structured, multi-phase workflows that automate the development lifecycle. They are strictly categorized by their role in the Unified Lifecycle Flow.
 
+#### **Semantic Tier Routing (The Tier Protocol)**
+The framework implements a dual-tier model routing strategy to optimize for intelligence, cost, and execution speed. This is configured in `.gemini/settings.json` via `modelConfigs.overrides`.
+
+- **The "Thinking" Tier (Clever/Pro):** High-reasoning agents (`planner`, `reviewer`, `learner`, `debugger`) are mapped to `gemini-3.1-pro-preview`. This ensures that architectural decisions, master-level learning, and forensic root-cause analysis are performed by the most capable models.
+- **The "Execution" Tier (Dumber/Lite):** High-volume, procedural agents (`writer`, `researcher`) are mapped to `gemini-2.5-flash-lite`. This provides high-velocity drafting and discovery without excessive context costs.
+
 #### Phase 1: Discovery & Audit (Read-Only)
 - **`/research`:** Deep-dive exploration producing exhaustive Markdown reports.
 - **`/maintenance`:** A non-destructive codebase audit generating a 'Maintenance Report Card'.
@@ -45,7 +51,7 @@ Commands define structured, multi-phase workflows that automate the development
 - **`/plan`:** The mandatory bridge. An interactive workflow that transitions between clarification, analysis of discovery artifacts, and strategy generation. It produces a persistent Markdown plan in `plans/`.
 
 #### Phase 3: Execution (Side-Effects)
-- **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the **strict TCR (Test-Commit-Revert) loop** and feature branch isolation.
+- **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the **strict TCR (Test-Commit-Revert) loop** and feature branch isolation. **Procedural Task Management:** The `/task` command operates exclusively via `.gemini/scripts/task.py`, which acts as the single source of truth for the project roadmap.
 - **`/draft`:** The content execution engine, transforming plans or `.review.md` reports into finished Markdown documents.
 - **`/document`:** Analyzes the codebase and project state to update the documentation suite.
 
@@ -87,6 +93,15 @@ The `pre-commit.py` hook implements a sophisticated cross-file validation strate
 3.  **Audit Trail Check:** Parses the **last entry** in the current day's journal file (`journal/YYYY-MM-DD.md`) and extracts its ISO timestamp.
 4.  **Temporal Consistency:** If the journal entry timestamp is **older** than the latest file change, the commit is blocked. This forces the agent (or user) to document the work *after* it is done but *before* it is finalized.
 
+### 🔍 Deep Dive: Procedural Task Management (`task.py`)
+
+The framework enforces a **CLI-First** roadmap discipline. The `TASKS.md` file is a machine-managed artifact produced by the `.gemini/scripts/task.py` utility.
+
+- **Data Integrity:** The script parses `TASKS.md` into a structured `Task` model, ensuring that IDs (e.g., `G.4`), labels, and dependencies are consistent.
+- **State Lifecycle:** Tasks move through a strictly defined lifecycle: `add` (Todo) -> `start` (In Progress) -> `archive` (Done/Archive).
+- **Migration Logic:** The script automatically assigns IDs and categorizes tasks during its initial run on a legacy `TASKS.md` file.
+- **Test Isolation:** The script's test suite (`tests/test_task_script.py`) utilizes the `GEMINI_TASKS_FILE` environment variable and `tempfile` to operate on a temporary roadmap, preventing verification logic from corrupting the actual project state.
+
 ### 4. Specialized Agents (`.gemini/agents/`)
 
 Instead of a single "do-it-all" AI, the framework delegates tasks to specialized sub-agents with restricted toolsets and focused personas.

docs/develop.md

@@ -31,10 +31,13 @@ Once a plan is approved, you move to execution. This is the **only** phase where
 
 #### For Code: The TCR Protocol
 The `/task` command is the primary tool for repository execution:
-- **`/task create`**: Adds a new task to `TASKS.md`.
-- **`/task work on ...`**: Implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
+- **`/task create`**: Adds a new task using the `task.py` script.
+- **`/task work on ...`**: Implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code. The orchestrator automatically uses `task.py` to mark the task as in-progress.
 - **`/task report`**: Provides a summary of the roadmap and current priorities.
-- **`/task update`**: Updates the status of an existing task.
+- **`/task update`**: Updates the status or plan-path of an existing task via the script.
+
+**CLI-First Roadmap Discipline:**
+The project roadmap (`TASKS.md`) must **never** be edited by hand. All task operations must be performed via the `.gemini/scripts/task.py` script or the corresponding `/task` actions. This ensures structural integrity and a verifiable audit trail.
 
 #### **The TCR Loop (Work Action)**
 

docs/index.md

@@ -46,10 +46,11 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 
 - **Deep Discovery:** Use `/research` for multi-phase domain investigations.
 - **Knowledge Mastering:** Use `/learn` to explore and codify new libraries or topics into permanent project skills.
+- **Semantic Tier Routing (The Tier Protocol):** Optimizes for intelligence, cost, and speed by mapping specialized agents (`planner`, `debugger`, `learner`, `reviewer`) to high-reasoning models.
 - **Architectural Planning:** Use `/plan` to generate persistent, actionable strategies.
 - **Forensic Debugging:** Use `/debug` for root-cause analysis without immediate (and potentially incorrect) fixes.
 - **Automated Documentation:** Use `/document` to keep the documentation synchronized with the evolving codebase.
-- **Roadmap Management:** Use `/task` to maintain a clear, version-controlled project roadmap in `TASKS.md`.
+- **Procedural Roadmap Management:** Use `/task` and the `.gemini/scripts/task.py` utility to maintain a structured, machine-managed project roadmap in `TASKS.md`.
 
 ## 🔄 Project Lifecycle
 

docs/user-guide.md

@@ -93,11 +93,34 @@ Your tool for project initialization.
 
 Your roadmap manager.
 
-- **How it works:** Manages a living `TASKS.md` document. Use it to `create` new tasks, `work` on existing ones, `report` on priorities, or `update` statuses. In the `work` mode, it acts as an orchestrator, delegating granular implementation steps to the specialized `coder` subagent.
+- **How it works:** Manages a living `TASKS.md` document **exclusively** via the `.gemini/scripts/task.py` utility. Use it to `create` new tasks, `start` work on existing ones, `report` on priorities, or `archive` completed tasks.
+- **Why it works:** By treating the roadmap as a machine-managed artifact, the framework ensures consistent formatting, automated ID generation (e.g., `G.4`), and a clear transition from `Todo` to `Archive` that aligns with the agent's turn lifecycle.
+- **Workflow Example:**
+    1.  `python .gemini/scripts/task.py add --label "New Feature" --description "..." --category "Logic"`
+    2.  `python .gemini/scripts/task.py start --task-id L.1` (marks as In Progress)
+    3.  Perform work via `/task work` (TCR loop).
+    4.  `python .gemini/scripts/task.py archive --task-id L.1` (moves to Archive)
 
 ### `/commit`
+...
+## 🌲 The Tier Protocol (Semantic Routing)
+
+To balance speed, cost, and architectural integrity, the framework implements a **Tier Protocol** for model routing. This is configured in `.gemini/settings.json`.
+
+### The "Thinking" Tier (Clever/Pro)
+Specialized agents that require high-reasoning and deep causal analysis are mapped to **`gemini-3.1-pro-preview`**.
+- **`planner`**: For architectural design and strategy.
+- **`debugger`**: For forensic root-cause analysis.
+- **`learner`**: For mastering new technologies without hallucinations.
+- **`reviewer`**: For critical editorial audits.
+
+### The "Execution" Tier (Dumber/Lite)
+Agents optimized for high-volume drafting and discovery are mapped to **`gemini-2.5-flash-lite`**.
+- **`writer`**: For section-by-section drafting.
+- **`researcher`**: For rapid information gathering.
+
+## 🔄 A Full Feature Development Walkthrough
 
-Brings order to your version history.
 
 - **How it works:** Instead of monolithic "WIP" commits, this command analyzes your `git diff` and logically groups modifications into cohesive units. It proposes a series of atomic, Conventional Commits (e.g., separating a feature update from a documentation tweak) for your approval.
 

journal/2026-03-24.md

@@ -5,3 +5,4 @@
 [2026-03-24T13:27:52] - Started procedural task management implementation
 [2026-03-24T13:36:58] - Implemented core Task model and parser/formatter logic
 [2026-03-24T14:22:22] - Implement procedural task management script and update core configs
+[2026-03-24T14:32:36] - Document Procedural Task Management and Tier Protocol (Semantic Routing)