tb_unblocked

Instructions

Implementation Reference

• src/tools/task-board.ts:366-396 (handler)

  The server.tool() call for 'tb_unblocked' that registers the tool and implements the handler. It queries tasks with status 'ready' or 'backlog', filters out those whose dependencies are all in 'done' status, and returns the unblocked list.

  server.tool(
    "tb_unblocked",
    "List all tasks that are ready to be worked on (no unresolved dependencies).",
    {
      board_id: z.string().describe("Board ID"),
    },
    async ({ board_id }) => {
      const db = getDb();
      const tasks = db
        .prepare(`SELECT * FROM tasks WHERE board_id = ? AND status IN ('ready', 'backlog') ORDER BY
                  CASE priority WHEN 'p0' THEN 0 WHEN 'p1' THEN 1 WHEN 'p2' THEN 2 WHEN 'p3' THEN 3 END`)
        .all(board_id) as Record<string, unknown>[];
  
      const unblocked = tasks.filter((t) => {
        const deps = JSON.parse(t.dependencies as string) as string[];
        if (deps.length === 0) return true;
        const done = db
          .prepare(`SELECT COUNT(*) as c FROM tasks WHERE id IN (${deps.map(() => "?").join(",")}) AND status = 'done'`)
          .get(...deps) as Record<string, number>;
        return done.c === deps.length;
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ board_id, unblocked_count: unblocked.length, tasks: unblocked }),
          },
        ],
      };
    }

• src/types/index.ts:71-83 (schema)

  TASK_STATUSES constant used by the tool to determine which statuses to query ('ready', 'backlog'), and TASK_PRIORITIES used for ordering results.

  export const TASK_STATUSES = [
    "backlog",
    "ready",
    "in_progress",
    "in_review",
    "done",
    "blocked",
  ] as const;
  
  export type TaskStatus = (typeof TASK_STATUSES)[number];
  
  export const TASK_PRIORITIES = ["p0", "p1", "p2", "p3"] as const;
  export type TaskPriority = (typeof TASK_PRIORITIES)[number];

• src/server.ts:18-20 (registration)

  The registerTaskBoardTools(server) call in createServer() that registers all task board tools including 'tb_unblocked'.

  registerSddTools(server);
  registerTaskBoardTools(server);
  registerFileTools(server);

• src/database/index.ts:12-30 (helper)

  The getDb() helper function that provides the SQLite database connection used by the tool handler.

  export function getDb(): Database.Database {
    if (db) return db;
  
    fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
  
    db = new Database(DB_PATH);
    db.pragma("journal_mode = WAL");
    db.pragma("synchronous = normal");
    db.pragma("cache_size = -32000");
    db.pragma("temp_store = memory");
    db.pragma("busy_timeout = 5000");
    db.pragma("foreign_keys = ON");
  
    const versionInfo = db.prepare("SELECT sqlite_version() as version").get() as { version: string };
    console.error(`ForgeSpec MCP: SQLite ${versionInfo.version}, WAL mode enabled`);
  
    initSchema(db);
    return db;
  }