feat(projects): add compact project task overview endpoint (additive)

Per review: this PR is now purely additive — endpoint + shared types + data
layer + docs + tests. No UI migration, no flag. The dashboard consumes the
new endpoint in a separate follow-up PR.

Added (this PR):
- shared/types.ts: ProjectTaskOverview, ProjectTaskPreview types + exports.
- data: listProjectTaskOverviews(previewLimit) — per-project status counts,
  metric totals (total*), retry/flag counts, small title previews bounded
  in SQL via row_number().
- api: GET /projects/overview route + repository re-export.
- docs: ### Project Task Overview section documents the actual wire shape
  (totalToken*, blockedTasks, completedTasks/...) — fixes the docs/contract
  mismatch from the #138 review (must-fix #1).

Not in this PR (deliberately):
- Dashboard UI migration (App.tsx, ProjectsOverview -> /overview): separate
  follow-up PR, per review (keep this PR purely additive).

Why no flag: the endpoint is purely additive — it adds a new route without
changing or replacing any existing contract. Nothing user-facing switches
behavior in this PR.

Verification: tsc clean (shared/data/api/web); data 214, api 405, web 666
tests green; build green.

Author: ichinya

docs/api.md

@@ -139,6 +139,64 @@ GET /projects
 ]
 ```
 
+### Project Task Overview
+
+```
+GET /projects/overview
+```
+
+Returns compact per-project task aggregates for the projects overview screen.
+This endpoint does not return full task rows.
+
+**Response:** `200 OK`
+
+```json
+[
+  {
+    "projectId": "uuid",
+    "totalTasks": 12,
+    "completedTasks": 2,
+    "verifiedTasks": 0,
+    "backlogTasks": 4,
+    "activeTasks": 6,
+    "blockedTasks": 1,
+    "autoModeTasks": 3,
+    "fixTasks": 1,
+    "totalRetries": 3,
+    "totalTokenInput": 1200,
+    "totalTokenOutput": 800,
+    "totalTokenTotal": 2000,
+    "totalCostUsd": 0.25,
+    "statusCounts": {
+      "backlog": 4,
+      "planning": 1,
+      "plan_ready": 2,
+      "implementing": 1,
+      "review": 1,
+      "blocked_external": 1,
+      "done": 2,
+      "verified": 0
+    },
+    "statusPreviews": {
+      "backlog": [{ "id": "task-1", "title": "Queued work" }],
+      "planning": [],
+      "plan_ready": [],
+      "implementing": [],
+      "review": [],
+      "blocked_external": [],
+      "done": [],
+      "verified": []
+    }
+  }
+]
+```
+
+`completedTasks` counts `done` + `verified`. `activeTasks` counts every status
+that is not `backlog`, `done`, or `verified`. `blockedTasks` counts
+`blocked_external`. `statusPreviews` lists are small (bounded in SQL) and
+include only task id/title pairs — never plan text, logs, or other detail-only
+fields.
+
 ### Create Project
 
 ```

docs/architecture.md

@@ -343,6 +343,9 @@ loads bounded:
   options, auto-review state, and QA markdown artifacts.
 - `GET /tasks/:id` remains the full task detail endpoint for task detail, chat,
   comments, and agent workflows.
+- `GET /projects/overview` uses `listProjectTaskOverviews()` to serve compact
+  per-project counts, metric totals, and small title previews without loading
+  every task row into the web client.
 
 ## Database
 

packages/api/src/__tests__/projects.test.ts

@@ -131,6 +131,71 @@ describe("projects API", () => {
     expect(await res.json()).toEqual([]);
   });
 
+  it("returns compact project task overviews", async () => {
+    const db = testDb.current;
+    db.insert(projects)
+      .values([
+        { id: "overview-a", name: "Overview A", rootPath: "/tmp/a" },
+        { id: "overview-b", name: "Overview B", rootPath: "/tmp/b" },
+      ])
+      .run();
+    db.insert(tasks)
+      .values([
+        {
+          id: "task-a-1",
+          projectId: "overview-a",
+          title: "Backlog item",
+          status: "backlog",
+          plan: "heavy plan",
+          implementationLog: "heavy implementation log",
+          reviewComments: "heavy review comments",
+          agentActivityLog: "heavy activity log",
+          tokenInput: 10,
+          tokenOutput: 20,
+          tokenTotal: 30,
+          costUsd: 0.25,
+        },
+        {
+          id: "task-a-2",
+          projectId: "overview-a",
+          title: "Done item",
+          status: "done",
+          retryCount: 2,
+        },
+        {
+          id: "task-b-1",
+          projectId: "overview-b",
+          title: "Other item",
+          status: "review",
+        },
+      ])
+      .run();
+
+    const res = await app.request("/projects/overview");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    const overviewA = body.find(
+      (overview: { projectId: string }) => overview.projectId === "overview-a",
+    );
+
+    expect(overviewA).toMatchObject({
+      projectId: "overview-a",
+      totalTasks: 2,
+      completedTasks: 1,
+      backlogTasks: 1,
+      totalRetries: 2,
+      totalTokenInput: 10,
+      totalTokenOutput: 20,
+      totalTokenTotal: 30,
+      totalCostUsd: 0.25,
+    });
+    expect(overviewA.statusCounts.backlog).toBe(1);
+    expect(overviewA.statusCounts.done).toBe(1);
+    expect(overviewA.statusPreviews.backlog).toEqual([{ id: "task-a-1", title: "Backlog item" }]);
+    expect(overviewA.statusPreviews.backlog[0]).not.toHaveProperty("plan");
+    expect(overviewA.statusPreviews.backlog[0]).not.toHaveProperty("implementationLog");
+  });
+
   it("rejects invalid root path for create", async () => {
     const res = await app.request("/projects", {
       method: "POST",

packages/api/src/repositories/projects.ts

@@ -7,6 +7,7 @@ import {
   createProject as createProjectRecord,
   deleteProject as deleteProjectRecord,
   findProjectById,
+  listProjectTaskOverviews,
   listProjects,
   type ProjectRow,
   updateProject as updateProjectRecord,
@@ -158,4 +159,4 @@ export function getProjectMcpServers(projectId: string): Record<string, unknown>
   }
 }
 
-export { listProjects, findProjectById };
+export { listProjects, listProjectTaskOverviews, findProjectById };

packages/api/src/routes/projects.ts

@@ -27,6 +27,7 @@ import { getAutoQueueMode, setAutoQueueMode } from "@aif/data";
 import { broadcast } from "../ws.js";
 import {
   listProjects,
+  listProjectTaskOverviews,
   findProjectById,
   createProject,
   updateProject,
@@ -194,6 +195,16 @@ projectsRouter.get("/", (c) => {
   return c.json(all);
 });
 
+// GET /projects/overview - compact task metrics and previews for the overview screen
+projectsRouter.get("/overview", (c) => {
+  const overview = listProjectTaskOverviews();
+  log.debug(
+    { projectCount: overview.length, responseType: "ProjectTaskOverview" },
+    "Listed project task overview",
+  );
+  return c.json(overview);
+});
+
 // POST /projects
 projectsRouter.post("/", jsonValidator(createProjectSchema), async (c) => {
   const body = c.req.valid("json");

packages/data/src/__tests__/index.test.ts

@@ -37,6 +37,7 @@ const {
   getLatestHumanComment,
   getLatestReworkComment,
   listProjects,
+  listProjectTaskOverviews,
   findProjectById,
   createProject,
   updateProject,
@@ -253,6 +254,68 @@ describe("data layer", () => {
     });
   });
 
+  describe("listProjectTaskOverviews", () => {
+    it("returns compact per-project aggregates and limited previews", () => {
+      seedProject("proj-2");
+      createTask({
+        projectId: "proj-1",
+        title: "Backlog A",
+        description: "D",
+        isFix: true,
+        tags: ["x"],
+      });
+      const firstBacklog = createTask({
+        projectId: "proj-1",
+        title: "Backlog first by position",
+        description: "D",
+        position: 10,
+      })!;
+      const backlog = listTasks("proj-1").find((task) => task.title === "Backlog A")!;
+      updateTask(backlog.id, {
+        tokenInput: 5,
+        tokenOutput: 6,
+        tokenTotal: 11,
+      });
+      const done = createTask({
+        projectId: "proj-1",
+        title: "Done B",
+        description: "D",
+        autoMode: false,
+      })!;
+      updateTaskStatus(done.id, "done", {
+        retryCount: 2,
+      });
+      updateTask(done.id, {
+        tokenInput: 10,
+        tokenOutput: 15,
+        tokenTotal: 25,
+        costUsd: 0.5,
+      });
+      createTask({ projectId: "proj-2", title: "Other project", description: "D" });
+
+      const overviews = listProjectTaskOverviews(1);
+      const proj1 = overviews.find((overview) => overview.projectId === "proj-1")!;
+      const proj2 = overviews.find((overview) => overview.projectId === "proj-2")!;
+
+      expect(proj1.totalTasks).toBe(3);
+      expect(proj1.completedTasks).toBe(1);
+      expect(proj1.backlogTasks).toBe(2);
+      expect(proj1.fixTasks).toBe(1);
+      expect(proj1.totalRetries).toBe(2);
+      expect(proj1.totalTokenInput).toBe(15);
+      expect(proj1.totalTokenOutput).toBe(21);
+      expect(proj1.totalTokenTotal).toBe(36);
+      expect(proj1.totalCostUsd).toBe(0.5);
+      expect(proj1.statusCounts.backlog).toBe(2);
+      expect(proj1.statusCounts.done).toBe(1);
+      expect(proj1.statusPreviews.backlog).toEqual([
+        { id: firstBacklog.id, title: "Backlog first by position" },
+      ]);
+      expect(proj1.statusPreviews.done).toEqual([{ id: done.id, title: "Done B" }]);
+      expect(proj2.totalTasks).toBe(1);
+    });
+  });
+
   describe("updateTask", () => {
     it("updates basic fields", () => {
       const t = createTask({ projectId: "proj-1", title: "Old", description: "D" });