@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/packages/local-runtime/src/project-settings.ts

@@ -2,23 +2,220 @@ import {
   PROJECT_CONFIG_PATH,
   type ProjectConfig,
   parseProjectConfig,
+  parseAgentCatalog,
   parseYaml,
   serializeYaml,
   type WorkspaceFileSystem,
 } from "@zaip-ai/core";
 
+const AGENT_CATALOG_PATH = ".agents/config/agents/catalog.yaml";
+const CODEX_CONFIG_PATH = ".codex/config.toml";
+const FRAMEWORK_LOCK_PATH = ".agents/config/framework.lock.yaml";
+const SQLITE_READ_MODEL_PATH = ".local/dashboard-sqlite/read-model.sqlite";
+export const SOFTWARE_ARCHITECTURE_PATH = "docs/SOFTWARE-ARCHITECTURE.md";
+
+export type ProjectOverview = {
+  framework_version: string | null;
+  metrics: Array<{
+    id: "agents" | "squads" | "skills" | "rules" | "hooks" | "database";
+    label: string;
+    value: number | string;
+  }>;
+  stack_components: Array<{
+    name: string;
+    version: string | null;
+    source: string | null;
+    verification: "exact" | "constraint" | "unavailable";
+  }>;
+  areas: Array<{
+    id:
+      | "brandbook"
+      | "design_system"
+      | "software_architecture"
+      | "growth_strategy"
+      | "marketing_strategy"
+      | "sales_playbook";
+    label: string;
+    artifact: string;
+    available: boolean;
+  }>;
+};
+
+const projectOverviewArtifacts: Array<Omit<ProjectOverview["areas"][number], "available">> = [
+  {
+    id: "software_architecture",
+    label: "Arquitetura de Software",
+    artifact: SOFTWARE_ARCHITECTURE_PATH,
+  },
+  { id: "design_system", label: "Design system", artifact: ".agents/design/DESIGN.md" },
+  { id: "brandbook", label: "Brandbook", artifact: ".agents/brand/brandbook.md" },
+  {
+    id: "marketing_strategy",
+    label: "Estratégia de Marketing",
+    artifact: ".agents/marketing/strategy.md",
+  },
+  { id: "sales_playbook", label: "Playbook de Sales", artifact: ".agents/sales/playbook.md" },
+  { id: "growth_strategy", label: "Estratégia de Growth", artifact: ".agents/growth/strategy.md" },
+];
+
 export async function readProjectSettings(filesystem: WorkspaceFileSystem): Promise<ProjectConfig> {
   return parseProjectConfig(parseYaml(await filesystem.readText(PROJECT_CONFIG_PATH)));
 }
 
+export async function readProjectOverview(
+  filesystem: WorkspaceFileSystem,
+): Promise<ProjectOverview> {
+  const [
+    catalog,
+    frameworkVersion,
+    sqliteActive,
+    installedSkills,
+    installedRules,
+    configuredHooks,
+  ] = await Promise.all([
+    filesystem.readText(AGENT_CATALOG_PATH).then(parseYaml).then(parseAgentCatalog),
+    readFrameworkVersion(filesystem),
+    filesystem.exists(SQLITE_READ_MODEL_PATH),
+    countInstalledSkills(filesystem),
+    countDirectMarkdownFiles(filesystem, ".agents/rules"),
+    countCodexHookEvents(filesystem),
+  ]);
+  return {
+    framework_version: frameworkVersion,
+    metrics: [
+      { id: "agents", label: "Agentes", value: catalog.agents.length },
+      { id: "squads", label: "Squads", value: catalog.squads.length },
+      { id: "skills", label: "Skills", value: installedSkills },
+      { id: "rules", label: "Rules", value: installedRules },
+      { id: "hooks", label: "Hooks", value: configuredHooks },
+      { id: "database", label: "Database", value: sqliteActive ? "Ativo" : "Inativo" },
+    ],
+    stack_components: await readVerifiedStackComponents(filesystem),
+    areas: await Promise.all(
+      projectOverviewArtifacts.map(async (area) => ({
+        ...area,
+        available: await filesystem.exists(area.artifact),
+      })),
+    ),
+  };
+}
+
+async function readFrameworkVersion(filesystem: WorkspaceFileSystem): Promise<string | null> {
+  try {
+    const lock = recordValue(parseYaml(await filesystem.readText(FRAMEWORK_LOCK_PATH)));
+    const version = recordValue(lock.framework).version;
+    return typeof version === "string" && version.trim() ? version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function countInstalledSkills(filesystem: WorkspaceFileSystem): Promise<number> {
+  const directories = await filesystem.listDirectories(".agents/skills");
+  const valid = await Promise.all(
+    directories.map((directory) => filesystem.exists(`${directory}/SKILL.md`)),
+  );
+  return valid.filter(Boolean).length;
+}
+
+async function countDirectMarkdownFiles(
+  filesystem: WorkspaceFileSystem,
+  directory: string,
+): Promise<number> {
+  const prefix = `${directory}/`;
+  const files = await filesystem.listFiles(directory, ".md");
+  return files.filter((path) => !path.slice(prefix.length).includes("/")).length;
+}
+
+async function countCodexHookEvents(filesystem: WorkspaceFileSystem): Promise<number> {
+  try {
+    const source = await filesystem.readText(CODEX_CONFIG_PATH);
+    const events = new Set(
+      [...source.matchAll(/^\s*\[\[hooks\.([A-Za-z0-9_-]+)\]\]\s*$/gm)].map((match) => match[1]),
+    );
+    return events.size;
+  } catch {
+    return 0;
+  }
+}
+
+async function readVerifiedStackComponents(
+  filesystem: WorkspaceFileSystem,
+): Promise<ProjectOverview["stack_components"]> {
+  const [rootPackage, dashboardRuntime, dashboardFrontend] = await Promise.all([
+    readPackageJson(filesystem, "package.json"),
+    readPackageJson(filesystem, ".agents/dashboard/packages/local-runtime/package.json"),
+    readPackageJson(filesystem, ".agents/dashboard/apps/frontend/package.json"),
+  ]);
+  return [
+    component("Node.js", process.versions.node, `Runtime observado: ${process.execPath}`, "exact"),
+    component("TypeScript", packageVersion(rootPackage, "typescript"), "package.json", "exact"),
+    component("Vite", packageVersion(rootPackage, "vite"), "package.json", "exact"),
+    component("Astro", packageVersion(rootPackage, "astro"), "package.json", "exact"),
+    component("Redis", packageVersion(rootPackage, "redis"), "package.json", "exact"),
+    component("BullMQ", packageVersion(rootPackage, "bullmq"), "package.json", "exact"),
+    component(
+      "Hono",
+      packageVersion(dashboardRuntime, "hono"),
+      ".agents/dashboard/packages/local-runtime/package.json",
+      "exact",
+    ),
+    component(
+      "React",
+      packageVersion(dashboardFrontend, "react"),
+      ".agents/dashboard/apps/frontend/package.json",
+      "exact",
+    ),
+  ];
+}
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+async function readPackageJson(
+  filesystem: WorkspaceFileSystem,
+  path: string,
+): Promise<PackageJson> {
+  try {
+    const value = JSON.parse(await filesystem.readText(path)) as unknown;
+    return typeof value === "object" && value !== null ? (value as PackageJson) : {};
+  } catch {
+    return {};
+  }
+}
+
+function packageVersion(pkg: PackageJson, name: string): string | null {
+  return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? null;
+}
+
+function component(
+  name: string,
+  version: string | null,
+  source: string,
+  verification: "exact" | "constraint",
+): ProjectOverview["stack_components"][number] {
+  return version === null
+    ? { name, version: null, source: null, verification: "unavailable" }
+    : { name, version, source, verification };
+}
+
 export async function persistProjectSettings(
   filesystem: WorkspaceFileSystem,
   input: unknown,
 ): Promise<ProjectConfig> {
-  const current = await readProjectSettings(filesystem);
+  const previousProjectSource = await filesystem.readText(PROJECT_CONFIG_PATH);
+  const current = parseProjectConfig(parseYaml(previousProjectSource));
   const requested = parseProjectConfig(input);
+  if (requested.tracking.storage_mode !== "tracked_sanitized") {
+    throw new TypeError("This project requires Git-native tracked_sanitized storage.");
+  }
   const candidate = parseProjectConfig({
     ...requested,
+    clients: current.clients,
+    tracking: current.tracking,
+    model_orchestration: current.model_orchestration,
     stack: {
       ...requested.stack,
       overrides: {
@@ -28,5 +225,199 @@ export async function persistProjectSettings(
     },
   });
   await filesystem.writeTextAtomic(PROJECT_CONFIG_PATH, serializeYaml(candidate));
+  try {
+    await filesystem.writeTextAtomic(
+      SOFTWARE_ARCHITECTURE_PATH,
+      renderSoftwareArchitecture(candidate),
+    );
+  } catch (cause) {
+    await filesystem.writeTextAtomic(PROJECT_CONFIG_PATH, previousProjectSource);
+    throw new Error(
+      "Project settings were rolled back because the software architecture summary could not be updated.",
+      { cause },
+    );
+  }
   return candidate;
 }
+
+const componentLabels: Record<string, string> = {
+  primary_language: "Linguagem principal",
+  backend_runtime: "Runtime backend",
+  backend_api: "Framework backend / API",
+  query_builder: "Query builder",
+  database: "Banco de dados",
+  auth_storage: "Autenticação e Storage",
+  cache_messaging: "Cache e mensageria",
+  async_queue: "Filas e processamento assíncrono",
+  backend_infrastructure: "Infraestrutura backend",
+  web_framework: "Framework do Web App",
+  web_language: "Linguagem do Web App",
+  web_build: "Build do Web App",
+  frontend_hosting: "Hospedagem do frontend",
+  site_framework: "Framework do site",
+  site_language: "Linguagem do site",
+  site_islands: "Componentes interativos",
+  site_build: "Build do site",
+  site_hosting: "Hospedagem do site",
+};
+
+const architectureLabels: Record<string, string> = {
+  backend_data_and_managed_services: "Dados e serviços gerenciados",
+  backend_api_and_business_rules: "APIs e regras de negócio",
+  backend_async_processing: "Filas e processamento assíncrono",
+  backend_infrastructure: "Infraestrutura backend",
+};
+
+export function renderSoftwareArchitecture(config: ProjectConfig): string {
+  const overrides = recordValue(config.stack.overrides);
+  const components = recordValue(overrides.components);
+  const languages = recordValue(overrides.languages);
+  const architecture = recordValue(overrides.architecture);
+  const componentRows = Object.entries(componentLabels).map(([id, label]) => {
+    const item = recordValue(components[id]);
+    return `| ${label} | ${markdownCell(item.name, "Não definido")} | ${markdownCell(item.version, "Não fixada")} | ${markdownCell(item.reference, "—")} |`;
+  });
+  const layoutRows = Object.entries(config.stack.layout ?? {}).map(
+    ([role, path]) => `| ${markdownCell(role)} | ${markdownCell(path)} |`,
+  );
+  const commandRows = Object.entries(config.stack.commands ?? {}).map(
+    ([name, command]) => `| ${markdownCell(name)} | \`${markdownCode(command)}\` |`,
+  );
+  const architectureSections = Object.entries(architecture).flatMap(([id, value]) => [
+    `### ${architectureLabels[id] ?? humanize(id)}`,
+    "",
+    ...markdownBullets(stringList(value)),
+    "",
+  ]);
+  const executionDetails =
+    config.execution?.runtime === "autonomous"
+      ? [
+          "- **Runtime:** autonomous",
+          `- **Provider:** ${markdownCell(config.execution.autonomous.provider)}`,
+          `- **Modelo-base:** ${markdownCell(config.execution.autonomous.model)}`,
+          `- **Paralelismo máximo:** ${config.execution.autonomous.max_parallelism}`,
+          `- **Lease configurado:** ${config.execution.autonomous.lease_ms} ms`,
+          `- **Limite total de invocações:** ${config.execution.autonomous.max_total_invocations ?? "Não definido"}`,
+        ]
+      : [`- **Runtime:** ${config.execution?.runtime ?? "manual (padrão implícito)"}`];
+  const assuranceDetails =
+    config.assurance === undefined
+      ? ["- Não configurada."]
+      : [
+          `- **Versão:** ${config.assurance.version}`,
+          `- **Profundidade padrão:** ${markdownCell(config.assurance.standard_depth)}`,
+          `- **Exigir commit final:** ${config.assurance.require_final_commit ? "Sim" : "Não"}`,
+        ];
+
+  return [
+    "---",
+    "schema_version: 1",
+    "kind: software-architecture",
+    `generated_from: ${PROJECT_CONFIG_PATH}`,
+    "---",
+    "",
+    "# Arquitetura de Software",
+    "",
+    `> Projeção gerada automaticamente pela página de configurações a partir de \`${PROJECT_CONFIG_PATH}\`. Não edite este arquivo manualmente.`,
+    "",
+    "## Projeto",
+    "",
+    `- **Nome:** ${markdownCell(config.project.name)}`,
+    `- **ID:** ${markdownCell(config.project.id)}`,
+    `- **Timezone:** ${markdownCell(config.project.timezone)}`,
+    "",
+    "## Perfil técnico",
+    "",
+    `- **Stack profile:** ${markdownCell(config.stack.id)}`,
+    `- **Linguagem:** ${markdownCell(config.stack.language, "Não definida")}`,
+    `- **API:** ${markdownCell(config.stack.api, "Não definida")}`,
+    `- **Query builder:** ${markdownCell(config.stack.query_builder, "Não definido")}`,
+    "",
+    "## Execução",
+    "",
+    ...executionDetails,
+    "",
+    "## Assurance",
+    "",
+    ...assuranceDetails,
+    "",
+    "## Componentes e versões",
+    "",
+    "| Responsabilidade | Tecnologia | Versão exata | Pacote / imagem / serviço |",
+    "| --- | --- | --- | --- |",
+    ...componentRows,
+    "",
+    "## Superfícies",
+    "",
+    "### Web App — Frontend",
+    "",
+    ...markdownBullets(stringList(languages.frontend)),
+    "",
+    "### Backend",
+    "",
+    ...markdownBullets(stringList(languages.backend)),
+    "",
+    "### Site e Landing Pages",
+    "",
+    ...markdownBullets(stringList(languages.site)),
+    "",
+    "## Decisões de arquitetura",
+    "",
+    ...(architectureSections.length > 0
+      ? architectureSections
+      : ["- Nenhuma decisão adicional registrada.", ""]),
+    "## Layout do código",
+    "",
+    "| Papel | Caminho |",
+    "| --- | --- |",
+    ...(layoutRows.length > 0 ? layoutRows : ["| Não definido | — |"]),
+    "",
+    "## Invariantes",
+    "",
+    ...markdownBullets(config.stack.invariants ?? []),
+    "",
+    "## Comandos de validação",
+    "",
+    "| Comando | Execução |",
+    "| --- | --- |",
+    ...(commandRows.length > 0 ? commandRows : ["| Não definido | — |"]),
+    "",
+  ].join("\n");
+}
+
+function recordValue(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (typeof item === "string" && item.length > 0) return [item];
+    const entries = Object.entries(recordValue(item));
+    return entries.length === 1 && typeof entries[0]?.[1] === "string"
+      ? [`${entries[0][0]}: ${entries[0][1]}`]
+      : [];
+  });
+}
+
+function markdownBullets(values: readonly string[]): string[] {
+  return values.length > 0
+    ? values.map((value) => `- ${markdownCell(value)}`)
+    : ["- Não definido."];
+}
+
+function markdownCell(value: unknown, fallback = "—"): string {
+  if (typeof value !== "string" || value.trim().length === 0) return fallback;
+  return value.trim().replaceAll("|", "\\|").replaceAll(/\r?\n/g, " ");
+}
+
+function markdownCode(value: unknown): string {
+  return markdownCell(value).replaceAll("`", "\\`");
+}
+
+function humanize(value: string): string {
+  const normalized = value.replaceAll("_", " ");
+  return normalized.charAt(0).toUpperCase() + normalized.slice(1);
+}

package/templates/.agents/dashboard/packages/local-runtime/src/runtime.mjs

@@ -9,8 +9,8 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 
 export const host = "127.0.0.1";
-export const defaultFrontendPort = 5173;
-export const defaultApiPort = 4317;
+export const defaultFrontendPort = 5273;
+export const defaultApiPort = 4417;
 const maxPortAttempts = 25;
 
 const sourceDirectory = dirname(fileURLToPath(import.meta.url));
@@ -19,9 +19,9 @@ export const workspaceRoot = resolve(packageRoot, "../../../..");
 export const frontendRoot = resolve(workspaceRoot, ".agents/dashboard/apps/frontend");
 const localNodeModules = resolve(packageRoot, "node_modules");
 const workspaceKey = createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
-export const sessionDirectory = join(tmpdir(), "zaip-aios", workspaceKey);
-export const dashboardSessionPath = join(sessionDirectory, "dashboard-session.json");
-export const launcherLogPath = join(sessionDirectory, "dashboard-launcher.log");
+export const sessionDirectory = join(tmpdir(), "zaip-aios", `dashboard-sqlite-${workspaceKey}`);
+export const dashboardSessionPath = join(sessionDirectory, "dashboard-sqlite-session.json");
+export const launcherLogPath = join(sessionDirectory, "dashboard-sqlite-launcher.log");
 
 export function createSessionToken() {
   return process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");

package/templates/.agents/dashboard/packages/local-runtime/src/server-board.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { boardPage } from "./server-board.js";
+
+describe("boardPage", () => {
+  it("returns only the bounded entity page without Run-derived enrichment", () => {
+    const task = {
+      id: "TASK-1",
+      title: "Task",
+      status: "executing",
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const prd = macro("PRD-1", "prd", [task.id]);
+    const spec = macro("SPEC-1", "spec", [task.id]);
+    const projection = {
+      changes: [],
+      tasks: [task],
+      prds: [prd],
+      specs: [spec],
+    } as unknown as Parameters<typeof boardPage>[0];
+    const page = boardPage(
+      projection,
+      "executing",
+      0,
+      10,
+      [],
+      { query: "", status: "", risk: "", origin: "", kind: "" },
+    );
+
+    expect(page.tasks[0]).toBe(task);
+    expect(page.prds[0]).toBe(prd);
+    expect(page.specs[0]).toBe(spec);
+    expect("runs" in page).toBe(false);
+  });
+
+  it("keeps the compact Task telemetry unchanged", () => {
+    const task = {
+      id: "TASK-EMPTY",
+      title: "Empty",
+      status: "executing",
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const projection = { changes: [], tasks: [task], prds: [], specs: [] } as unknown as Parameters<
+      typeof boardPage
+    >[0];
+    const page = boardPage(
+      projection,
+      "executing",
+      0,
+      10,
+      [],
+      { query: "", status: "", risk: "", origin: "", kind: "" },
+    );
+    expect(page.tasks[0]).toBe(task);
+  });
+
+});
+
+function macro(id: string, kind: "prd" | "spec", taskIds: string[]) {
+  return {
+    id,
+    kind,
+    title: id,
+    parent_id: null,
+    task_ids: taskIds,
+    lifecycle_status: "active",
+    work_status: "executing",
+    updated_at: "2026-08-08T10:00:00Z",
+    duration_ms: null,
+    usage: { total: { tokens: { total: null }, cost: { brl: null } } },
+  };
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-board.ts

@@ -0,0 +1,179 @@
+import {
+  macroWorkStage,
+  taskWorkStage,
+  type WorkStage,
+} from "@zaip-ai/dashboard-operations/work-board-model";
+import type { Context } from "hono";
+import type { buildCanonicalOperationsProjection } from "./server-projections.js";
+
+type BoardStage = WorkStage;
+export type BoardClassification = "lite" | "standard" | "critical" | "empty" | "structured" | "rework";
+
+interface BoardFilters {
+  query: string;
+  status: string;
+  risk: string;
+  origin: string;
+  kind: string;
+}
+
+export function boardFilters(context: Context): BoardFilters {
+  return {
+    query: (context.req.query("query") ?? "").trim().toLocaleLowerCase(),
+    status: context.req.query("status") ?? "",
+    risk: context.req.query("risk") ?? "",
+    origin: context.req.query("origin") ?? "",
+    kind: context.req.query("kind") ?? "",
+  };
+}
+
+export function boardStage(value: string | undefined): BoardStage {
+  const stages: readonly BoardStage[] = [
+    "definition",
+    "planning",
+    "ready",
+    "executing",
+    "verifying",
+    "completed",
+    "blocked",
+    "cancelled",
+    "failed",
+  ];
+  if (value === undefined || !stages.includes(value as BoardStage))
+    throw new Error("A valid Kanban stage is required");
+  return value as BoardStage;
+}
+
+/** Deliberately omits Runs: the board loads a small stage-local cursor page. */
+export function boardPage(
+  projection: Awaited<ReturnType<typeof buildCanonicalOperationsProjection>>,
+  stage: BoardStage,
+  offset: number,
+  limit: number,
+  manualOrder: readonly string[],
+  filters: BoardFilters,
+) {
+  const sourceByChange = new Map(
+    projection.changes.map((change) => [change.id, change.source.type] as const),
+  );
+  const matchesQuery = (values: readonly (string | null | undefined)[]) =>
+    filters.query === "" ||
+    values.some((value) => value?.toLocaleLowerCase().includes(filters.query));
+  const taskMatches = (task: (typeof projection.tasks)[number]) =>
+    (filters.status === "" || taskWorkStage(task) === filters.status) &&
+    (filters.risk === "" || task.risk === filters.risk) &&
+    (filters.origin === "" ||
+      (sourceByChange.get(task.change_id) ?? (task.spec_id === null ? "task" : "spec")) ===
+        filters.origin) &&
+    matchesQuery([
+      task.id,
+      task.title,
+      task.short_name,
+      task.objective,
+      task.change_id,
+      task.spec_id,
+    ]);
+  const macroMatches = (macro: (typeof projection.prds)[number]) =>
+    filters.risk === "" &&
+    filters.origin === "" &&
+    (filters.status === "" || macroWorkStage(macro, projection.tasks) === filters.status) &&
+    matchesQuery([macro.id, macro.title, macro.parent_id]);
+  const filteredTasks = projection.tasks.filter(taskMatches);
+  const filteredPrds = projection.prds.filter(macroMatches);
+  const filteredSpecs = projection.specs.filter(macroMatches);
+  const items = [
+    ...filteredPrds.map((row) => ({ kind: "prd" as const, row })),
+    ...filteredSpecs.map((row) => ({ kind: "spec" as const, row })),
+    ...filteredTasks.map((row) => ({ kind: "task" as const, row })),
+  ]
+    .filter(
+      (item) =>
+        (item.kind === "task"
+          ? taskWorkStage(item.row)
+          : macroWorkStage(item.row, projection.tasks)) === stage,
+    )
+    .toSorted((left, right) => {
+      const order = new Map(manualOrder.map((id, index) => [id, index] as const));
+      return (
+        (order.get(left.row.id) ?? Number.MAX_SAFE_INTEGER) -
+          (order.get(right.row.id) ?? Number.MAX_SAFE_INTEGER) ||
+        String(right.row.updated_at ?? "").localeCompare(String(left.row.updated_at ?? "")) ||
+        left.row.id.localeCompare(right.row.id)
+      );
+    });
+  const allStageItems = items.filter(
+    (item) =>
+      (item.kind === "task"
+        ? taskWorkStage(item.row)
+        : macroWorkStage(item.row, projection.tasks)) === stage,
+  );
+  const stageItems =
+    filters.kind === ""
+      ? allStageItems
+      : allStageItems.filter((item) => item.kind === filters.kind);
+  const page = stageItems.slice(offset, offset + limit);
+  const ids = new Set(page.map((item) => item.row.id));
+  return {
+    stage,
+    offset,
+    total: stageItems.length,
+    totals_by_kind: {
+      all: allStageItems.length,
+      task: allStageItems.filter((item) => item.kind === "task").length,
+      prd: allStageItems.filter((item) => item.kind === "prd").length,
+      spec: allStageItems.filter((item) => item.kind === "spec").length,
+    },
+    prds: page
+      .filter((item) => item.kind === "prd")
+      .map((item) => item.row),
+    specs: page
+      .filter((item) => item.kind === "spec")
+      .map((item) => item.row),
+    tasks: page
+      .filter((item) => item.kind === "task")
+      .map((item) => item.row),
+    changes: projection.changes.filter((change) =>
+      change.task_ids.some((taskId) => ids.has(taskId)),
+    ),
+  };
+}
+
+/**
+ * Canonical cross-stage population behind the Overview classification donut.
+ * It deliberately derives macro classification from the same projection fields
+ * used by overview_metrics, rather than from the browser's bounded task page.
+ */
+export function classificationPage(
+  projection: Awaited<ReturnType<typeof buildCanonicalOperationsProjection>>,
+  kind: "task" | "spec" | "prd",
+  classification: BoardClassification,
+  offset: number,
+  limit: number,
+) {
+  const macroClassification = (macro: (typeof projection.specs)[number]) =>
+    macro.rework_run_count > 0 ? "rework" : macro.task_count > 0 ? "structured" : "empty";
+  const items =
+    kind === "task"
+      ? projection.tasks.filter((task) => task.risk === classification)
+      : (kind === "spec" ? projection.specs : projection.prds).filter(
+          (macro) => macroClassification(macro) === classification,
+        );
+  const sorted = items.toSorted(
+    (left, right) =>
+      String(right.updated_at ?? right.created_at ?? "").localeCompare(
+        String(left.updated_at ?? left.created_at ?? ""),
+      ) || left.id.localeCompare(right.id),
+  );
+  const page = sorted.slice(offset, offset + limit);
+  return {
+    offset,
+    total: sorted.length,
+    prds: kind === "prd" ? page : [],
+    specs: kind === "spec" ? page : [],
+    tasks: kind === "task" ? page : [],
+    changes:
+      kind === "task"
+        ? projection.changes.filter((change) => page.some((task) => change.task_ids.includes(task.id)))
+        : [],
+  };
+}