mk:task-queue

Task Queue & Ownership Tracker

Manages task assignment and file ownership during parallel execution.

Task Queue

Tasks are tracked in session-state/task-queue.json:

{
  "tasks": [
    {
      "id": 1,
      "description": "Implement API endpoints",
      "owner": null,
      "status": "pending",
      "ownership": ["src/api/*", "src/routes/*"],
      "blocked_by": []
    },
    {
      "id": 2,
      "description": "Implement UI components",
      "owner": null,
      "status": "pending",
      "ownership": ["src/components/*", "src/pages/*"],
      "blocked_by": []
    }
  ]
}

Task Lifecycle

pending → claimed (agent assigned) → in_progress → completed
                                   → blocked (dependency not met)

Claiming Protocol

1. Agent requests next available task
2. Queue returns lowest-ID task where: status=pending AND blocked_by all completed
3. Agent declares ownership globs
4. Queue checks for overlap with other in_progress tasks
5. If overlap: REJECT claim, report conflict to orchestrator
6. If no overlap: ASSIGN task, set status=in_progress, record owner

Ownership Enforcement

Each task declares file ownership via glob patterns. Before any file write, check if the file matches the agent's declared ownership.

| Action | Owned File? | Result | |--------|------------|--------| | Read | Any | Always allowed | | Write/Edit | Owned | Allowed | | Write/Edit | Not owned | STOP — report ownership violation | | Write/Edit | Overlapping | STOP — report conflict to orchestrator |

Integration

• Orchestrator creates the task queue when decomposing parallel work
• Parallel agents claim and complete tasks
• Orchestrator monitors queue for completion and triggers integration test
• Queue is ephemeral (session-state/) — recreated per parallel execution

Gotchas

• Race condition on claims: Two agents reading task-queue.json simultaneously may both claim the same task. Mitigation: orchestrator is the sole claim-serializer — agents REQUEST claims through orchestrator, never self-claim directly
• Ownership globs must not overlap: src/api/ and src/api/auth/ overlap — the more specific glob must be in the SAME task, not split across agents
• Queue file doesn't auto-create: Orchestrator must create session-state/task-queue.json before dispatching parallel agents. If missing, agents should STOP and report, not create it themselves
• Completed tasks are not removed: Tasks stay in queue with status=completed for audit trail. Queue is cleaned up only when the parallel execution phase ends