feat(tasks): implement procedural task management script

Author: apiad

.gemini/commands/task.toml

@@ -1,35 +1,43 @@
 description = "Manage the project roadmap (TASKS.md) and implement tasks via a strict, agent-delegated TCR loop."
 
 prompt = """
-You are an expert project manager. Your goal is to manage the project's roadmap in `TASKS.md`.
+You are an expert project manager. Your goal is to manage the project's roadmap in `TASKS.md` EXCLUSIVELY via the `.gemini/scripts/task.py` CLI.
+**CRITICAL: NEVER modify `TASKS.md` directly with file-editing tools. You MUST use the script.**
+
 Depending on the user's intent or arguments, perform one of the following actions:
 
 ### **Action: Create**
-Add a new task to `TASKS.md`.
-1. Read `TASKS.md` to understand the current structure and existing tasks.
+Add a new task using the script.
+1. Run `python .gemini/scripts/task.py --help` if you need to recall the `add` subcommand arguments.
 2. If the user provided a task description in the arguments, use it. Otherwise, identify the task from the recent conversation context.
-3. Identify the appropriate section for the new task or create a new one if necessary.
-4. Add the task with a clear description and status 'Todo' [ ].
-5. Ensure the task follows the existing formatting conventions and verify the file after the update.
+3. Determine an appropriate `label`, `description`, `category`, and `complexity`.
+4. Execute: `python .gemini/scripts/task.py add --label "<label>" --description "<description>" --category "<category>" --complexity <complexity>`.
+5. Verify the update by reading the new `TASKS.md`.
 
 ### **Action: Work**
 Implement a task using a strict, agent-delegated Test-Commit-Revert (TCR) protocol on a feature branch.
+
 1. **Pre-flight Verification:**
    - Verify `git status --porcelain` is empty (clean tree).
    - Verify `git branch --show-current` is `main`.
    - Run `make test` and ensure all tests pass. If any fail, notify the user and stop.
+
 2. **Task Setup:**
-   - Identify the target task from arguments or context.
-   - Mark it as `[/] In Progress (@apiad)` in `TASKS.md`.
+   - Identify the target task ID from arguments or context.
+   - Run `python .gemini/scripts/task.py start --task-id <ID>` to mark it in progress.
    - Generate a descriptive kebab-case branch name (e.g., `feature/task-description`).
    - Create and switch to the branch: `git checkout -b <branch-name>`.
+
 3. **The TCR Loop (Delegation):**
    - Break the task into granular, testable steps based on the project plan (if one exists).
    - For each step, **delegate the implementation to the specialized `coder` subagent**:
      - Instruct the `coder` to follow its Red-Green-Verify mantra (write test, implement code, verify).
      - **If the `coder` reports success:** Run `git add . && git commit -m "Step: <description of changes>"`.
      - **If the `coder` reports failure:** Run `git checkout .` to revert the current step to the last green state.
    - Use `ask_user` to report each step's result and confirm before proceeding to the next one.
+
+NOTE: The coder subagent is very dumb, only for grunt coding. Make sure to give it detailed instructions and to split the task into very small steps. If the coder keeps failing and the task explanation cannot be simplified further, then fix it yourself. If that doesn't work, ask the user for clarification and possibly update the task plan.
+
 4. **Integration & Finalization:**
    - Once all steps are complete, run a full `make test`.
    - Use `ask_user` to request permission to merge back to `main`.
@@ -38,20 +46,20 @@ Implement a task using a strict, agent-delegated Test-Commit-Revert (TCR) protoc
      - Merge the branch: `git merge <branch-name>`.
      - Run `make test` on `main`.
      - Delete the feature branch: `git branch -d <branch-name>`.
-   - Update `TASKS.md` to reflect the final state (mark as `[x] Done`).
+   - Run `python .gemini/scripts/task.py archive --task-id <ID>` to mark it done.
 
 ### **Action: Report**
 Produce a strategic report of current tasks.
-1. Analyze `TASKS.md` and list all [ ] Todo or [/] In Progress tasks.
+1. Read `TASKS.md` and list all active tasks (Todo or In Progress).
 2. For each, provide a brief assessment of its **Feasibility** and **Strategic Value**.
 3. Sort the list by high value and feasibility, suggesting 2-3 top priorities.
 
 ### **Action: Update**
 Synchronize `TASKS.md` with the project's progress.
 1. Read `TASKS.md`, `CHANGELOG.md`, and recent `journal/` entries.
 2. Analyze uncommitted changes and conversation context.
-3. Update task statuses: mark completed as [x] Done, move current work to [/] In Progress, and add new high-level features if missing.
-4. If a task was implemented differently, update its description.
+3. Use the script subcommands (`start`, `cancel`, `archive`) to update task statuses as appropriate.
+4. If a task requires a linked plan, use `python .gemini/scripts/task.py attach-plan --task-id <ID> --plan-path <path>`.
 5. Verify the file after the update.
 
 ---

.gemini/scripts/task.py

@@ -13,7 +13,7 @@ def __init__(self, id=None, label=None, description=None, category=None, complex
         self.category = category
         self.complexity = complexity
         self.dependencies = dependencies if dependencies is not None else []
-        self.status = status # e.g., "todo", "in_progress", "done"
+        self.status = status # e.g., "todo", "in_progress", "done", "cancelled"
         self.plan_path = plan_path
 
     def __repr__(self):
@@ -34,13 +34,15 @@ def __eq__(self, other):
 
 # --- Regex Patterns ---
 # New format: - [Status] **[ID]** Label: Description (Complexity: X) [Deps: Y] (See plan: Z)
+# Note: Label is optional in some contexts but the script expects it for new format
 NEW_TASK_REGEX = re.compile(
-    r'^- \[(?P<status>[^\]]+)\] \*\*(?P<id>[^ ]+)\*\* (?P<label>[^:]+): (?P<description>.*?)(?: \(Complexity: (?P<complexity>\d+)\))?(?: \[Deps: (?P<dependencies>.*?)\])?(?: \(See plan: (?P<plan_path>.*?)\))?$'
+    r'^- \[(?P<status>[^\]]*)\] \*\*(?P<id>[^ ]+)\*\*(?: (?P<label>[^:]+):)? (?P<description>.*?)(?: \(Complexity: (?P<complexity>\d+)\))?(?: \[Deps: (?P<dependencies>.*?)\])?(?: \(See plan: (?P<plan_path>.*?)\))?$'
 )
 # Old format: - [ ] Description (See plan: ...)
 OLD_TASK_REGEX = re.compile(
     r'^- \[(?P<status>[^\]]*)\] (?P<description>.*?)(?: \(See plan: (?P<plan_path>.*?)\))?$'
 )
+
 HEADER_WARNING = """# Tasks
 
 > **WARNING: NEVER MODIFY THIS FILE BY HAND. USE THE SCRIPT INSTEAD.**
@@ -51,7 +53,7 @@ def __eq__(self, other):
 
 def parse_task_line(line):
     line = line.strip()
-    if not line or line.startswith('#') or line.startswith('>'):
+    if not line or not line.startswith('- ['):
         return None
 
     new_match = NEW_TASK_REGEX.match(line)
@@ -63,22 +65,35 @@ def parse_task_line(line):
             dependencies = [dep.strip() for dep in deps_str.split(',') if dep.strip()]
 
         complexity = int(data.get('complexity')) if data.get('complexity') else 0
+        
+        status_char = data.get('status')
+        status_map = {" ": "todo", "/": "in_progress", "x": "done", "-": "cancelled"}
+        status = status_map.get(status_char, "todo")
+
+        label = data.get('label')
+        if label:
+            label = label.strip()
+
         return Task(
             id=data.get('id'),
-            label=data.get('label'),
-            description=data.get('description'),
+            label=label,
+            description=data.get('description').strip(),
             category=None,
             complexity=complexity,
             dependencies=dependencies,
-            status=data.get('status'),
+            status=status,
             plan_path=data.get('plan_path')
         )
 
     old_match = OLD_TASK_REGEX.match(line)
     if old_match:
         data = old_match.groupdict()
-        status = data.get('status').strip()
-        if not status: status = "todo"
+        status_char = data.get('status').strip()
+        if status_char == 'x': status = "done"
+        elif status_char == '/': status = "in_progress"
+        elif status_char == '-': status = "cancelled"
+        else: status = "todo"
+
         return Task(
             id=None,
             label=None,
@@ -93,16 +108,16 @@ def parse_task_line(line):
 
 def parse_tasks_file(file_content):
     tasks = []
-    current_category = None
+    current_category = "General"
     lines = file_content.splitlines()
 
     for line in lines:
         stripped_line = line.strip()
+        if not stripped_line:
+            continue
         if stripped_line.startswith("## Active Tasks"):
-            current_category = None
             continue
         elif stripped_line.startswith("## Archive"):
-            current_category = None
             continue
         elif stripped_line.startswith("### "):
             current_category = stripped_line[4:].strip()
@@ -117,14 +132,20 @@ def parse_tasks_file(file_content):
 # --- Formatter Functions ---
 
 def format_task_to_line(task):
+    status_map = {"todo": " ", "in_progress": "/", "done": "x", "cancelled": "-"}
+    status_str = status_map.get(task.status, task.status)
+    
     if task.id is not None:
         complexity_str = f" (Complexity: {task.complexity})" if task.complexity != 0 else ""
-        deps_str = f" [Deps: {', '.join(task.dependencies)}]"
+        deps_str = ""
+        if task.dependencies: # Only add [Deps: ...] if there are dependencies
+            deps_str = f" [Deps: {', '.join(task.dependencies)}]"
         plan_path_str = f" (See plan: {task.plan_path})" if task.plan_path else ""
-        return f"- [{task.status}] **{task.id}** {task.label}: {task.description}{complexity_str}{deps_str}{plan_path_str}"
+        label_str = f" {task.label}:" if task.label else ""
+        return f"- [{status_str}] **{task.id}**{label_str} {task.description}{complexity_str}{deps_str}{plan_path_str}"
     else:
         plan_path_str = f" (See plan: {task.plan_path})" if task.plan_path else ""
-        return f"- [{task.status}] {task.description}{plan_path_str}"
+        return f"- [{status_str}] {task.description}{plan_path_str}"
 
 def topological_sort(tasks):
     adj = defaultdict(list)
@@ -153,9 +174,7 @@ def topological_sort(tasks):
                 queue.append(v)
 
     sorted_tasks = [task_map[tid] for tid in sorted_tasks_ids]
-    # Add tasks with IDs that were not in the sort (cycles)
     remaining_with_ids = sorted([t for t in tasks if t.id and t.id not in sorted_tasks_ids], key=lambda t: (t.complexity, t.id))
-    # Add tasks without IDs
     without_ids = sorted([t for t in tasks if not t.id], key=lambda t: (t.complexity, t.description))
 
     return sorted_tasks + remaining_with_ids + without_ids
@@ -167,7 +186,7 @@ def format_tasks_to_markdown(tasks):
     def group_by_category(task_list):
         grouped = defaultdict(list)
         for t in task_list:
-            cat = t.category if t.category else "Uncategorized"
+            cat = t.category if t.category else "General"
             grouped[cat].append(t)
         return grouped
 
@@ -180,35 +199,136 @@ def group_by_category(task_list):
     if not active_tasks:
         lines.append("No active tasks.")
     else:
+        # Sort categories alphabetically for consistent output
         for cat in sorted(active_grouped.keys()):
+            lines.append("")
             lines.append(f"### {cat}")
             for t in topological_sort(active_grouped[cat]):
                 lines.append(format_task_to_line(t))
 
+    lines.append("")
     lines.append("## Archive")
     if not archive_tasks:
         lines.append("No archived tasks.")
     else:
+        # Sort categories alphabetically for consistent output
         for cat in sorted(archive_grouped.keys()):
+            lines.append("")
             lines.append(f"### {cat}")
-            # Archive sorted by complexity then id/description
             cat_tasks = sorted(archive_grouped[cat], key=lambda t: (t.complexity, t.id if t.id else t.description))
             for t in cat_tasks:
                 lines.append(format_task_to_line(t))
 
     return "\n".join(lines) + "\n"
 
+def generate_next_task_id(tasks, category):
+    prefix = category[0].upper()
+    max_num = 0
+    for task in tasks:
+        if task.id and task.id.startswith(prefix + "."):
+            try:
+                num_part = task.id.split('.')[-1]
+                current_num = int(num_part)
+                if current_num > max_num:
+                    max_num = current_num
+            except ValueError:
+                continue
+    return f"{prefix}.{max_num + 1}"
+
+def add_task(tasks, label, description, category, complexity, dependencies, plan_path):
+    new_task_id = generate_next_task_id(tasks, category)
+    new_task = Task(
+        id=new_task_id,
+        label=label,
+        description=description,
+        category=category,
+        complexity=complexity,
+        dependencies=dependencies,
+        status='todo',
+        plan_path=plan_path
+    )
+    tasks.append(new_task)
+    return tasks
+
+# --- New Functionality ---
+
+def update_task(tasks, task_id, **kwargs):
+    """
+    Searches for a task by its ID and updates the specified attributes.
+    If the task is not found, prints a warning to sys.stderr.
+    Returns the potentially modified list of tasks.
+    """
+    task_found = False
+    for task in tasks:
+        if task.id == task_id:
+            for key, value in kwargs.items():
+                setattr(task, key, value)
+            task_found = True
+            break # Assuming task IDs are unique
+    if not task_found:
+        print(f"Warning: Task with ID {task_id} not found.", file=sys.stderr)
+    return tasks
+
 def main():
     parser = argparse.ArgumentParser(description="Task management script for TASKS.md.")
-    # For now we just implement the reformat on call
-    tasks_file_path = "TASKS.md"
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+
+    # Add command
+    parser_add = subparsers.add_parser('add', help='Add a new task')
+    parser_add.add_argument('--label', required=True)
+    parser_add.add_argument('--description', required=True)
+    parser_add.add_argument('--category', required=True)
+    parser_add.add_argument('--complexity', type=int, default=0)
+    parser_add.add_argument('--dependencies', type=str, default="")
+    parser_add.add_argument('--plan-path', type=str, default=None)
+
+    # New commands: start, cancel, archive, attach-plan
+    parser_start = subparsers.add_parser('start', help='Set task status to in_progress')
+    parser_start.add_argument('--task-id', required=True)
+
+    parser_cancel = subparsers.add_parser('cancel', help='Set task status to cancelled')
+    parser_cancel.add_argument('--task-id', required=True)
+
+    parser_archive = subparsers.add_parser('archive', help='Set task status to done')
+    parser_archive.add_argument('--task-id', required=True)
+
+    parser_attach_plan = subparsers.add_parser('attach-plan', help='Set the task\'s plan path')
+    parser_attach_plan.add_argument('--task-id', required=True)
+    parser_attach_plan.add_argument('--plan-path', required=True)
+
+    args = parser.parse_args()
+
+    # Use environment variable to override TASKS.md for testing
+    import os
+    tasks_file_path = os.environ.get("GEMINI_TASKS_FILE", "TASKS.md")
+
     try:
         with open(tasks_file_path, 'r') as f:
             content = f.read()
     except FileNotFoundError:
-        sys.exit(1)
+        content = HEADER_WARNING + "\n"
 
     tasks = parse_tasks_file(content)
+
+    # Migration: Assign IDs to tasks that don't have them
+    for task in tasks:
+        if task.id is None:
+            task.id = generate_next_task_id(tasks, task.category if task.category else "General")
+
+    if args.command == 'add':
+        deps = [d.strip() for d in args.dependencies.split(',') if d.strip()]
+        tasks = add_task(tasks, args.label, args.description, args.category, args.complexity, deps, args.plan_path)
+    
+    # Handle new commands
+    elif args.command == 'start':
+        tasks = update_task(tasks, args.task_id, status="in_progress")
+    elif args.command == 'cancel':
+        tasks = update_task(tasks, args.task_id, status="cancelled")
+    elif args.command == 'archive':
+        tasks = update_task(tasks, args.task_id, status="done")
+    elif args.command == 'attach-plan':
+        tasks = update_task(tasks, args.task_id, plan_path=args.plan_path)
+
     formatted = format_tasks_to_markdown(tasks)
     with open(tasks_file_path, 'w') as f:
         f.write(formatted)