@oqtopus-team/pi-qdash 0.1.5 → 0.1.8

package/README.md

@@ -16,7 +16,7 @@ It uses [`@oqtopus-team/qdash-client`](https://www.npmjs.com/package/@oqtopus-te
 
 ## Key Features
 
-- **Read-only investigation**: dedicated tools to inspect chips, qubits, couplings, calibration task results, executions, issues, and Forum posts. Secrets are redacted from tool output.
+- **Read-only investigation**: dedicated tools to inspect chips, qubits, couplings, calibration task results, task knowledge (`qdash_get_task_knowledge`), executions, issues, and Forum posts. Secrets are redacted from tool output.
 - **Dashboards and insights**: compact dashboards, triage overviews, target-level incident reports, degradation reports, and wiring insights.
 - **Agent calibration workflow**: create agent sessions, submit and track agent actions, and commit/apply calibration candidates. Write operations are approval-gated.
 - **Figures**: fetch calibration PNG/JSON figures and render them in the interactive TUI.
@@ -43,7 +43,9 @@ Or try it without installing:
 pi -e npm:@oqtopus-team/pi-qdash
 ```
 
-Requires pi v0.74.0 or later.
+Requires Node.js 20 or later and pi v0.74.0 or later. The extension tracks
+`@oqtopus-team/qdash-client` 1.9.x and uses its authenticated high-level and
+generated API clients.
 
 ## Quick Start
 

package/extensions/qdash.ts

@@ -4,7 +4,13 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import { QDashClient, defaultConfigPath, type DownloadedFile, type TaskResultFigureOptions } from "@oqtopus-team/qdash-client";
+import {
+  QDashClient,
+  defaultConfigPath,
+  type CooldownResponse,
+  type DownloadedFile,
+  type TaskResultFigureOptions,
+} from "@oqtopus-team/qdash-client";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
@@ -19,6 +25,7 @@ import { toTextToolResult, toToolResult } from "./lib/results.js";
 import { ansi, boxLinesToWidth, boxed, formatNumber, textComponent } from "./lib/render.js";
 import { plotSeriesLines, timeseriesPlotComponent, timeseriesPoints } from "./lib/timeseries-plot.js";
 import { installQDashWriteGate } from "./lib/write-gate.js";
+import { registerTaskKnowledgeTool } from "./tools/task-knowledge.js";
 import { registerTimeseriesComparisonTool } from "./tools/timeseries.js";
 import { analyzeWiringMarkdown, wiringInsightLines, type WiringInsights } from "./lib/wiring-analysis.js";
 
@@ -397,6 +404,9 @@ async function defaultChipId(client: QDashClient, chipId?: string): Promise<stri
   return chipId ?? currentContext.chipId ?? client.getDefaultChipId();
 }
 
+// Keep arbitrary GET access isolated for qdash_raw_get and legacy filters that are
+// not represented in the generated OpenAPI surface. Normal operations should use
+// QDashClient's high-level methods or client.api so upgrades remain type-checked.
 async function rawGet<T>(client: QDashClient, path: string, query?: Record<string, unknown>): Promise<T> {
   return (client as unknown as { get<T>(path: string, query?: Record<string, unknown>): Promise<T> }).get(path, cleanQuery(query));
 }
@@ -472,19 +482,6 @@ function requireValue(value: string | undefined, name: string): string {
   return value;
 }
 
-type CooldownRecord = {
-  cooldown_id: string;
-  cryo_id: string;
-  description?: string;
-  started_at: string;
-  ended_at?: string | null;
-  chip_ids?: string[];
-  wiring_info?: string;
-  wiring_blocks?: Record<string, unknown>[];
-};
-
-type CooldownListResponse = { cooldowns?: CooldownRecord[] };
-
 type CooldownWiringParams = {
   profile?: string;
   configPath?: string;
@@ -502,7 +499,7 @@ type WiringInsightParams = CooldownWiringParams & {
   color?: boolean;
 };
 
-function newestCooldown(cooldowns: CooldownRecord[]): CooldownRecord | undefined {
+function newestCooldown(cooldowns: CooldownResponse[]): CooldownResponse | undefined {
   return [...cooldowns].sort((a, b) => {
     const activeDifference = Number(a.ended_at != null) - Number(b.ended_at != null);
     if (activeDifference !== 0) return activeDifference;
@@ -514,15 +511,15 @@ async function resolveCooldownWiring(params: CooldownWiringParams) {
   params = applyQDashContext(params);
   const client = await makeClient(params);
   let selection: string;
-  let cooldown: CooldownRecord;
+  let cooldown: CooldownResponse;
   let resolvedChipId = params.chipId ?? currentContext.chipId;
 
   if (params.cooldownId) {
-    cooldown = await rawGet<CooldownRecord>(client, `/cooldowns/${pathPart(params.cooldownId)}`);
+    cooldown = await client.api.getCooldown(params.cooldownId);
     selection = "explicit cooldownId";
   } else {
     resolvedChipId = params.chipId ?? (params.cryoId ? undefined : await defaultChipId(client));
-    const response = await rawGet<CooldownListResponse>(client, "/cooldowns", {
+    const response = await client.api.listCooldowns({
       cryo_id: params.cryoId,
       chip_id: resolvedChipId,
     });
@@ -531,7 +528,7 @@ async function resolveCooldownWiring(params: CooldownWiringParams) {
       const scope = params.cryoId ? `cryo ${params.cryoId}` : `chip ${resolvedChipId}`;
       throw new Error(`No cooldown containing wiring information was found for ${scope}`);
     }
-    cooldown = await rawGet<CooldownRecord>(client, `/cooldowns/${pathPart(selected.cooldown_id)}`);
+    cooldown = await client.api.getCooldown(selected.cooldown_id);
     selection = params.cryoId ? "active/newest cooldown for cryo" : "active/newest cooldown for chip";
   }
 
@@ -539,14 +536,14 @@ async function resolveCooldownWiring(params: CooldownWiringParams) {
   const wiringInfo = typeof cooldown.wiring_info === "string" ? cooldown.wiring_info.trim() : "";
   const includeBlocks = params.includeBlocks === true || !wiringInfo;
   const history = params.includeHistory
-    ? await rawGet(client, `/cooldowns/${pathPart(cooldown.cooldown_id)}/wiring-events`, {
+    ? await client.api.listCooldownWiringEvents(cooldown.cooldown_id, {
         limit: params.historyLimit ?? 20,
         skip: 0,
       })
     : undefined;
   let cryostat: unknown;
   try {
-    cryostat = await rawGet(client, `/cryostats/${pathPart(cooldown.cryo_id)}`);
+    cryostat = await client.api.getCryostat(cooldown.cryo_id);
   } catch {
     // Wiring remains useful on servers where cryostat detail is not accessible.
   }
@@ -594,9 +591,9 @@ async function buildDashboard(params: { profile?: string; configPath?: string; u
   const chipId = await defaultChipId(client, params.chipId);
   const [chips, openIssues, recentExecutions, failedTaskResults, provenanceStats] = await Promise.allSettled([
     client.listChips(),
-    rawGet(client, "/issues", { is_closed: false, limit }),
-    rawGet(client, "/executions", { chip_id: chipId, limit }),
-    rawGet(client, "/task-results", { chip_id: chipId, status: "failed", limit }),
+    client.api.listIssues({ is_closed: false, limit }),
+    client.api.listExecutions({ chip_id: chipId, limit }),
+    client.api.listTaskResults({ chip_id: chipId, status: "failed", limit }),
     client.getProvenanceStats(),
   ]);
   const value = <T>(result: PromiseSettledResult<T>): T | { error: string } => result.status === "fulfilled" ? result.value : { error: result.reason instanceof Error ? result.reason.message : String(result.reason) };
@@ -738,7 +735,7 @@ async function buildRecentCalibrationSummary(params: { profile?: string; configP
   const chipId = await defaultChipId(client, params.chipId);
   const end = new Date();
   const start = new Date(end.getTime() - (params.withinHours ?? 24) * 3600_000);
-  const payload = await rawGet(client, "/task-results", { chip_id: chipId, start_from: start.toISOString(), start_to: end.toISOString(), limit: params.limit ?? 30 });
+  const payload = await client.api.listTaskResults({ chip_id: chipId, start_from: start.toISOString(), start_to: end.toISOString(), limit: params.limit ?? 30 });
   const items = arrayFromPayload(payload).filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object");
   const byTarget = new Map<string, Record<string, unknown>[]>();
   for (const item of items) {
@@ -939,7 +936,7 @@ async function buildTargetOperationsReport(params: { profile?: string; configPat
   const [latestTarget, results, issues, forumPosts] = await Promise.all([
     kind === "qubit" ? client.getChipQubit(chipId, id) : client.getChipCoupling(chipId, id),
     client.listTaskResults({ chipId, qid, couplingId, startAt: start.toISOString(), endAt: end.toISOString(), limit }),
-    rawGet(client, "/issues", { is_closed: false, limit: 100 }),
+    client.api.listIssues({ is_closed: false, limit: 100 }),
     client.listForumPosts({ chipId, status: "open", targetType: kind, targetId: id, limit }),
   ]);
   const recentResults = arrayFromPayload(results).filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object");
@@ -1123,7 +1120,7 @@ async function buildCalibrationValidation(params: { profile?: string; configPath
   const task = await client.getTaskResult(params.taskId) as unknown as Record<string, unknown>;
   const status = firstString(task, ["status"])?.toLowerCase() ?? "unknown";
   const figurePaths = taskFigurePaths(task, 20);
-  const issuesPayload = await rawGet(client, `/task-results/${pathPart(params.taskId)}/issues`).catch(() => []);
+  const issuesPayload = await client.api.getTaskResultIssues(params.taskId).catch(() => []);
   const issues = arrayFromPayload(issuesPayload).filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object");
   const afterExecutionId = firstString(task, ["execution_id", "executionId"]);
   const comparison = params.beforeExecutionId && afterExecutionId
@@ -1256,10 +1253,10 @@ async function buildDashboardInsights(params: { profile?: string; configPath?: s
   const start = new Date(end.getTime() - (params.withinHours ?? 168) * 3600_000);
   const [forums, issues, failed, metrics, aiInsights] = await Promise.allSettled([
     client.listForumPosts({ chipId, status: "open", limit }),
-    rawGet(client, "/issues", { is_closed: false, limit }),
-    rawGet(client, "/task-results", { chip_id: chipId, status: "failed", start_from: start.toISOString(), start_to: end.toISOString(), limit }),
+    client.api.listIssues({ is_closed: false, limit }),
+    client.api.listTaskResults({ chip_id: chipId, status: "failed", start_from: start.toISOString(), start_to: end.toISOString(), limit }),
     client.getChipMetrics(chipId),
-    rawGet(client, `/chips/${pathPart(chipId)}/ai-insights`, { latest_only: true, start_at: start.toISOString(), end_at: end.toISOString() }),
+    client.api.getDashboardAiInsights(chipId, { latest_only: true, start_at: start.toISOString(), end_at: end.toISOString() }),
   ]);
   const value = <T>(result: PromiseSettledResult<T>): T | undefined => result.status === "fulfilled" ? result.value : undefined;
   const insightMap = new Map<string, DashboardInsight>();
@@ -1485,19 +1482,19 @@ async function executeQuery(params: QDashQueryParams) {
     case "chip_qubit": return client.getChipQubit(await defaultChipId(client, params.chipId), requireValue(params.qid, "qid"));
     case "chip_couplings": return client.listChipCouplings(await defaultChipId(client, params.chipId), { limit: params.limit, offset: params.offset });
     case "chip_coupling": return client.getChipCoupling(await defaultChipId(client, params.chipId), requireValue(params.couplingId, "couplingId"));
-    case "cryostats": return rawGet(client, "/cryostats");
-    case "cryostat": return rawGet(client, `/cryostats/${pathPart(requireValue(params.cryoId, "cryoId"))}`);
-    case "cooldowns": return rawGet(client, "/cooldowns", { cryo_id: params.cryoId, chip_id: params.chipId });
-    case "cooldown": return rawGet(client, `/cooldowns/${pathPart(requireValue(params.cooldownId, "cooldownId"))}`);
-    case "cooldown_wiring_events": return rawGet(client, `/cooldowns/${pathPart(requireValue(params.cooldownId, "cooldownId"))}/wiring-events`, { limit: params.limit, skip: params.skip });
+    case "cryostats": return client.api.listCryostats();
+    case "cryostat": return client.api.getCryostat(requireValue(params.cryoId, "cryoId"));
+    case "cooldowns": return client.api.listCooldowns({ cryo_id: params.cryoId, chip_id: params.chipId });
+    case "cooldown": return client.api.getCooldown(requireValue(params.cooldownId, "cooldownId"));
+    case "cooldown_wiring_events": return client.api.listCooldownWiringEvents(requireValue(params.cooldownId, "cooldownId"), { limit: params.limit, skip: params.skip });
     case "timeseries": return client.getTaskResultsTimeseries({ chipId: await defaultChipId(client, params.chipId), parameter: requireValue(params.parameter, "parameter"), tag: params.tag, qid: params.qid, startAt: requireValue(params.startAt, "startAt"), endAt: requireValue(params.endAt, "endAt") });
     case "task_results": return rawGet(client, "/task-results", { chip_id: params.chipId, task_name: params.taskName, qid: params.qid, coupling_id: params.couplingId, execution_id: params.executionId, username: params.username, status: params.status, start_from: params.startFrom ?? params.startAt, start_to: params.startTo ?? params.endAt, message_contains: params.messageContains, limit: params.limit, skip: params.skip });
     case "task_result": return client.getTaskResult(requireValue(params.taskId, "taskId"));
-    case "task_note": return rawGet(client, `/task-results/${pathPart(requireValue(params.taskId, "taskId"))}/note`);
-    case "task_result_issues": return rawGet(client, `/task-results/${pathPart(requireValue(params.taskId, "taskId"))}/issues`);
-    case "qubit_latest": return rawGet(client, "/task-results/qubits/latest", { chip_id: await defaultChipId(client, params.chipId), task: requireValue(params.task ?? params.taskName, "task") });
+    case "task_note": return client.api.getTaskNote(requireValue(params.taskId, "taskId"));
+    case "task_result_issues": return client.api.getTaskResultIssues(requireValue(params.taskId, "taskId"));
+    case "qubit_latest": return client.api.getLatestQubitTaskResults({ chip_id: await defaultChipId(client, params.chipId), task: requireValue(params.task ?? params.taskName, "task") });
     case "qubit_history": return rawGet(client, `/task-results/qubits/${pathPart(requireValue(params.qid, "qid"))}/history`, { chip_id: await defaultChipId(client, params.chipId), task: requireValue(params.task ?? params.taskName, "task"), date: requireValue(params.date, "date") });
-    case "coupling_latest": return rawGet(client, "/task-results/couplings/latest", { chip_id: await defaultChipId(client, params.chipId), task: requireValue(params.task ?? params.taskName, "task") });
+    case "coupling_latest": return client.api.getLatestCouplingTaskResults({ chip_id: await defaultChipId(client, params.chipId), task: requireValue(params.task ?? params.taskName, "task") });
     case "coupling_history": return rawGet(client, `/task-results/couplings/${pathPart(requireValue(params.couplingId, "couplingId"))}/history`, { chip_id: await defaultChipId(client, params.chipId), task: requireValue(params.task ?? params.taskName, "task"), date: requireValue(params.date, "date") });
     case "tasks": return client.listTasks(params.backend);
     case "task_knowledge": return params.taskName ? client.getTaskKnowledge(params.taskName) : client.listTaskKnowledge();
@@ -1507,23 +1504,26 @@ async function executeQuery(params: QDashQueryParams) {
     case "files_tree": return client.getFilesTree();
     case "file_content": return client.getFileContent(requireValue(params.path, "path"));
     case "git_status": return client.getGitStatus();
-    case "issues": return rawGet(client, "/issues", { task_id: params.taskId, is_closed: params.isClosed, limit: params.limit, skip: params.skip });
-    case "issue_knowledge": return rawGet(client, "/issue-knowledge", { status: params.status, task_name: params.taskName, limit: params.limit, skip: params.skip });
+    case "issues": return client.api.listIssues({ task_id: params.taskId, is_closed: params.isClosed, limit: params.limit, skip: params.skip });
+    case "issue_knowledge": return client.api.listIssueKnowledge({ status: params.status, task_name: params.taskName, limit: params.limit, skip: params.skip });
     case "flows": return client.listFlows();
     case "flow": return client.getFlow(requireValue(params.flowName, "flowName"));
     case "flow_templates": return client.listFlowTemplates();
     case "flow_template": return client.getFlowTemplate(requireValue(params.templateId, "templateId"));
-    case "flow_helper_files": return rawGet(client, "/flows/helpers");
-    case "flow_helper_file": return rawGet(client, `/flows/helpers/${pathPart(requireValue(params.filename, "filename"))}`);
+    case "flow_helper_files": return client.api.listFlowHelperFiles();
+    case "flow_helper_file": return client.api.getFlowHelperFile(requireValue(params.filename, "filename"));
     case "executions": return rawGet(client, "/executions", { chip_id: params.chipId, flow_name: params.flowName, status: params.status, skip: params.skip, limit: params.limit });
     case "execution": return client.getExecution(requireValue(params.executionId, "executionId"));
-    case "ai_reviews": return rawGet(client, "/task-results/ai-review", { chip_id: params.chipId, task_name: params.taskName, status: params.status, decision: params.decision, latest_only: params.latestOnly, skip: params.skip, limit: params.limit });
-    case "ai_review_runs": return rawGet(client, "/task-results/ai-review/runs", { chip_id: params.chipId, task_name: params.taskName, skip: params.skip, limit: params.limit });
-    case "ai_review_run": return rawGet(client, `/task-results/ai-review/runs/${pathPart(requireValue(params.reviewRunId, "reviewRunId"))}`);
+    case "ai_reviews": return client.api.listTaskResultAiReviews({ chip_id: params.chipId, task_name: params.taskName, status: params.status, decision: params.decision, latest_only: params.latestOnly, skip: params.skip, limit: params.limit });
+    case "ai_review_runs": return client.api.listTaskResultAiReviewRuns({ chip_id: params.chipId, task_name: params.taskName, skip: params.skip, limit: params.limit });
+    case "ai_review_run": return client.api.getTaskResultAiReviewRun(requireValue(params.reviewRunId, "reviewRunId"));
     case "forum_posts": return client.listForumPosts({ status: params.status, chipId: params.chipId, limit: params.limit, skip: params.skip });
     case "provenance_stats": return client.getProvenanceStats();
-    case "provenance_history": return rawGet(client, "/provenance/history", { parameter_name: params.parameterName ?? params.parameter, qid: params.qid, limit: params.limit });
-    case "provenance_changes": return rawGet(client, "/provenance/changes", { parameter_names: params.parameterName ?? params.parameter, within_hours: params.withinHours, limit: params.limit });
+    case "provenance_history": return client.api.getParameterHistory({ parameter_name: requireValue(params.parameterName ?? params.parameter, "parameterName"), qid: requireValue(params.qid, "qid"), limit: params.limit });
+    case "provenance_changes": {
+      const parameterName = params.parameterName ?? params.parameter;
+      return client.getRecentChanges({ parameterNames: parameterName ? [parameterName] : undefined, withinHours: params.withinHours, limit: params.limit });
+    }
     case "provenance_lineage": return client.getProvenanceLineage(requireValue(params.entityId, "entityId"));
     case "provenance_impact": return client.getProvenanceImpact(requireValue(params.entityId, "entityId"));
   }
@@ -1531,6 +1531,7 @@ async function executeQuery(params: QDashQueryParams) {
 
 export default function qdashExtension(pi: ExtensionAPI) {
   installQDashWriteGate(pi);
+  registerTaskKnowledgeTool(pi, { makeClient });
 
   pi.registerTool({
     name: "qdash_config_info",

package/extensions/tools/task-knowledge.ts

@@ -0,0 +1,144 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { QDashClient } from "@oqtopus-team/qdash-client";
+import { Type } from "typebox";
+
+import { toTextToolResult } from "../lib/results.js";
+
+type TaskKnowledgeParams = {
+  profile?: string;
+  configPath?: string;
+  useEnv?: boolean;
+  taskName: string;
+  format?: "markdown" | "summary";
+};
+
+type TaskKnowledge = {
+  name: string;
+  summary?: string;
+  what_it_measures?: string;
+  expected_result?: Record<string, unknown>;
+  failure_modes?: Array<Record<string, unknown>>;
+  check_questions?: string[];
+};
+
+type TaskKnowledgeList = { items?: Array<{ name?: string }> } | Array<{ name?: string }>;
+
+export type TaskKnowledgeDependencies = {
+  makeClient(params: TaskKnowledgeParams): Promise<QDashClient>;
+};
+
+function text(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function bulletLines(items: string[]): string[] {
+  return items.length ? items.map((item) => `- ${item}`) : ["- Not documented."];
+}
+
+export function taskKnowledgeSummary(knowledge: TaskKnowledge): string {
+  const expected = knowledge.expected_result ?? {};
+  const expectedLines = [
+    text(expected.description),
+    text(expected.good_visual) && `Good visual: ${text(expected.good_visual)}`,
+    text(expected.typical_range) && `Typical range: ${text(expected.typical_range)}`,
+  ].filter((value): value is string => Boolean(value));
+  const failureLines = (knowledge.failure_modes ?? []).map((mode) => {
+    const description = text(mode.description) ?? "Unspecified failure mode";
+    const cause = text(mode.cause);
+    const nextAction = text(mode.next_action);
+    return [description, cause && `Cause: ${cause}`, nextAction && `Next: ${nextAction}`].filter(Boolean).join(" — ");
+  });
+
+  return [
+    `# ${knowledge.name}`,
+    "",
+    ...(text(knowledge.summary) ? [text(knowledge.summary)!, ""] : []),
+    "## What it measures",
+    "",
+    text(knowledge.what_it_measures) ?? "Not documented.",
+    "",
+    "## Expected result",
+    "",
+    ...bulletLines(expectedLines),
+    "",
+    "## Failure modes",
+    "",
+    ...bulletLines(failureLines),
+    "",
+    "## Check questions",
+    "",
+    ...bulletLines((knowledge.check_questions ?? []).filter((item) => Boolean(text(item)))),
+  ].join("\n");
+}
+
+function knownNames(payload: TaskKnowledgeList): string[] {
+  const items = Array.isArray(payload) ? payload : payload.items ?? [];
+  return items.map((item) => text(item.name)).filter((name): name is string => Boolean(name));
+}
+
+export function similarTaskNames(taskName: string, names: string[], limit = 5): string[] {
+  const needle = taskName.toLowerCase();
+  return names
+    .filter((name) => {
+      const candidate = name.toLowerCase();
+      return candidate.startsWith(needle) || needle.startsWith(candidate) || candidate.includes(needle) || needle.includes(candidate);
+    })
+    .sort((a, b) => {
+      const aPrefix = a.toLowerCase().startsWith(needle) ? 0 : 1;
+      const bPrefix = b.toLowerCase().startsWith(needle) ? 0 : 1;
+      return aPrefix - bPrefix || a.length - b.length || a.localeCompare(b);
+    })
+    .slice(0, limit);
+}
+
+function notFound(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const value = error as { status?: unknown; statusCode?: unknown; response?: { status?: unknown }; message?: unknown };
+  return value.status === 404 || value.statusCode === 404 || value.response?.status === 404 || /\b404\b|not found/i.test(String(value.message ?? ""));
+}
+
+export function registerTaskKnowledgeTool(pi: Pick<ExtensionAPI, "registerTool">, deps: TaskKnowledgeDependencies): void {
+  pi.registerTool({
+    name: "qdash_get_task_knowledge",
+    label: "QDash Task Knowledge",
+    description: "Get task knowledge when asked how to interpret a result, what curve or outcome is expected, which failure modes apply, or what to try next.",
+    promptSnippet: "Read QDash task knowledge before interpreting calibration results",
+    promptGuidelines: [
+      "Use qdash_get_task_knowledge before interpreting task-specific physics, expected curves, failure modes, or next diagnostic checks.",
+      "This tool is read-only and does not execute tasks or change parameters.",
+    ],
+    parameters: Type.Object({
+      profile: Type.Optional(Type.String({ description: "QDash profile name. Defaults to env when QDASH_BASE_URL is set, otherwise 'default'." })),
+      configPath: Type.Optional(Type.String({ description: "Optional path to qdash config.ini." })),
+      useEnv: Type.Optional(Type.Boolean({ description: "Force QDASH_* environment variables instead of a profile." })),
+      taskName: Type.String({ description: "QDash task name, for example CheckRabi." }),
+      format: Type.Optional(Type.Union([Type.Literal("markdown"), Type.Literal("summary")], { description: "Output format. Defaults to markdown." })),
+    }),
+    async execute(_toolCallId, params: TaskKnowledgeParams) {
+      const client = await deps.makeClient(params);
+      const format = params.format ?? "markdown";
+      try {
+        const data = format === "summary"
+          ? await client.getTaskKnowledge(params.taskName) as unknown as TaskKnowledge
+          : await client.getTaskKnowledgeMarkdown(params.taskName);
+        const markdown = format === "summary"
+          ? taskKnowledgeSummary(data as TaskKnowledge)
+          : typeof data === "string"
+            ? data
+            : text((data as { markdown?: unknown })?.markdown) ?? JSON.stringify(data, null, 2);
+        return toTextToolResult(markdown, data, { taskName: params.taskName, format, found: true });
+      } catch (error) {
+        if (!notFound(error)) throw error;
+        const listed = await client.listTaskKnowledge() as TaskKnowledgeList;
+        const suggestions = similarTaskNames(params.taskName, knownNames(listed));
+        const markdown = [
+          `No task knowledge found for \`${params.taskName}\`.`,
+          ...(suggestions.length ? ["", "Similar known task names:", ...suggestions.map((name) => `- \`${name}\``)] : ["", "No similar known task names were found."]),
+        ].join("\n");
+        return toTextToolResult(markdown, { taskName: params.taskName, found: false, suggestions }, { taskName: params.taskName, format, found: false });
+      }
+    },
+  });
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",
   "author": "OQTOPUS Team <oqtopus-team@googlegroups.com>",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oqtopus-team/pi-qdash.git"
@@ -24,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@oqtopus-team/qdash-client": "^0.1.4"
+    "@oqtopus-team/qdash-client": "^1.9.11"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/skills/qdash/SKILL.md

@@ -9,55 +9,45 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
 
 ## Preferred tools
 
-1. `qdash_config_info` — check profile names and non-secret connection settings.
-2. Prefer dedicated read-only tools when they match the task:
-   - `qdash_list_chips`, `qdash_get_default_chip`
-   - `qdash_get_chip_metrics`, `qdash_list_chip_qubits`, `qdash_list_chip_couplings`
-   - `qdash_list_cryostats`, `qdash_list_cooldowns`
-   - `qdash_get_cooldown_wiring`, `qdash_wiring_insights`, `qdash_list_cooldown_wiring_events`
-   - `qdash_get_timeseries`, `qdash_plot_timeseries`, `qdash_inspect_timeseries_csv`, `qdash_compare_timeseries`
-   - `qdash_list_task_results`, `qdash_get_task_result`
-   - `qdash_list_issues`
-   - `qdash_list_flows`, `qdash_get_flow`
-   - `qdash_list_executions`, `qdash_get_execution`
-   - `qdash_list_ai_reviews`, `qdash_get_provenance_stats`
-   - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies`
-   - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`, `qdash_build_qcal_evidence`
-   - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
-   - `qdash_preview_forum_image_reply`, then `qdash_create_forum_image_reply` for confirmed uploads of locally generated analysis images
-3. Use harness overview tools for status and triage:
-   - `qdash_investigate` for natural-language requests to investigate or compare recent calibration, target history, figures, failures, issues, and Forum context
-   - `qdash_compare_calibration` for read-only before/after comparison of repeated target calibration results
-   - `qdash_dashboard`
-   - `qdash_dashboard_insights`
-   - `qdash_recent_calibration_summary`
-   - `qdash_recommend_next_action`
-   - `qdash_triage_overview`
-4. Use agent calibration workflow tools when the user explicitly wants an agent workflow:
-   - `qdash_create_agent_session`
-   - `qdash_get_agent_session`
-   - `qdash_submit_agent_action`
-   - `qdash_get_agent_action`, `qdash_list_agent_actions`, `qdash_wait_agent_action`
-   - `qdash_list_agent_action_candidates`
-   - `qdash_execute_agent_action`
-   - `qdash_commit_agent_candidate`, `qdash_commit_agent_campaign_candidates`
-   - `qdash_get_agent_candidate_commit`, `qdash_apply_agent_candidate_commit`, `qdash_wait_agent_candidate_apply`
-5. Use `qdash_query` for common read-only QDash operations not covered by a dedicated tool:
-   - `chips`, `default_chip`, `metrics_config`, `chip_metrics`
-   - `chip_qubits`, `chip_qubit`, `chip_couplings`, `chip_coupling`
-   - `cryostats`, `cryostat`, `cooldowns`, `cooldown`, `cooldown_wiring_events`
-   - `timeseries`, `task_results`, `task_result`, `task_note`, `task_result_issues`
-   - `qubit_latest`, `qubit_history`, `coupling_latest`, `coupling_history`
-   - `tasks`, `task_knowledge`, `task_knowledge_markdown`
-   - `projects`, `project`, `files_tree`, `file_content`, `git_status`
-   - `issues`, `issue_knowledge`
-   - `flows`, `flow`, `flow_templates`, `flow_template`, `flow_helper_files`, `flow_helper_file`
-   - `executions`, `execution`, `ai_reviews`, `ai_review_runs`, `ai_review_run`
-   - `forum_posts`, `provenance_stats`, `provenance_history`, `provenance_changes`, `provenance_lineage`, `provenance_impact`
-6. `qdash_raw_get` — read-only GET endpoints not covered by `qdash_query`.
+Prefer the dedicated tool that matches the question. Use `qdash_query` only as a fallback when no dedicated tool covers the read-only operation.
+
+1. Dedicated read-only tools:
+   - `qdash_list_chips`, `qdash_get_default_chip` — list chips or resolve the active chip
+   - `qdash_get_chip_metrics`, `qdash_list_chip_qubits`, `qdash_list_chip_couplings` — inspect chip metrics and topology targets
+   - `qdash_list_cryostats`, `qdash_list_cooldowns` — establish cryostat and cooldown context
+   - `qdash_get_cooldown_wiring`, `qdash_wiring_insights`, `qdash_list_cooldown_wiring_events` — inspect current wiring, attenuation, and changes
+   - `qdash_get_timeseries`, `qdash_plot_timeseries` — inspect one target metric over time
+   - `qdash_inspect_timeseries_csv`, `qdash_compare_timeseries` — validate and compare multiple QDash or CSV timeseries
+   - `qdash_list_task_results`, `qdash_get_task_result` — find and inspect calibration results
+   - `qdash_get_task_knowledge` — interpret a task's purpose, expected result, failure modes, and check questions
+   - `qdash_list_issues` — inspect tracked issues
+   - `qdash_list_flows`, `qdash_get_flow` — list or inspect calibration flows
+   - `qdash_list_executions`, `qdash_get_execution`, `qdash_wait_execution`, `qdash_compare_executions` — inspect, await, or compare executions
+   - `qdash_list_ai_reviews`, `qdash_get_provenance_stats` — inspect AI reviews or provenance status
+   - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies` — inspect Forum context
+   - `qdash_preview_forum_evidence_reply`, `qdash_preview_forum_image_reply` — preview evidence or image replies without writing
+   - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`, `qdash_build_qcal_evidence` — inspect or package figure evidence
+2. Read-only overview and planning tools:
+   - `qdash_dashboard`, `qdash_dashboard_insights`, `qdash_triage_overview` — summarize status, insights, and investigation priorities
+   - `qdash_investigate`, `qdash_target_report`, `qdash_compare_calibration` — investigate target history and compare calibrations
+   - `qdash_recent_calibration_summary`, `qdash_recommend_next_action` — summarize outcomes and recommend a safe next action
+   - `qdash_degradation_report`, `qdash_plan_calibration`, `qdash_validate_calibration` — inspect drift, plan work, and validate results
+3. Write-oriented workflow tools, only after explicit confirmation:
+   - `qdash_create_agent_session`, `qdash_submit_agent_action`, `qdash_execute_agent_action` — create or execute a scoped agent workflow
+   - `qdash_commit_agent_candidate`, `qdash_commit_agent_campaign_candidates` — commit reviewed candidate parameters
+   - `qdash_apply_agent_candidate_commit` — apply a reviewed candidate commit
+   - `qdash_create_forum_post`, `qdash_update_forum_post` — create or update Forum content
+   - `qdash_create_forum_evidence_reply`, `qdash_create_forum_image_reply` — publish previously reviewed evidence replies
+4. Agent workflow state tools:
+   - `qdash_get_agent_session`, `qdash_get_agent_action`, `qdash_list_agent_actions`, `qdash_wait_agent_action` — inspect agent workflow state
+   - `qdash_list_agent_action_candidates`, `qdash_get_agent_candidate_commit`, `qdash_wait_agent_candidate_apply` — inspect candidates and apply status
+5. `qdash_query` — fallback for read-only operations without a dedicated tool.
+6. `qdash_raw_get` — last-resort read-only GET for an uncovered endpoint.
 
 ## Session context
 
+When running in pi CLI, use `qdash_config_info` if the profile or non-secret connection settings are unclear.
+
 Use these commands to make pi behave like a QDash-specific harness with persistent session-local context:
 
 ```text
@@ -76,6 +66,20 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 
 Prefer the current context when the user has already selected a profile/chip/session. Tools use that context when parameters are omitted.
 
+## Cooldown-aware investigations
+
+Treat cooldown identity as mandatory investigation context whenever comparing calibration results, coherence metrics, drift, failures, or Forum evidence across time:
+
+1. Call `qdash_list_cooldowns` for the chip early in the investigation and record the relevant `cooldown_id`, `started_at`, and `ended_at` boundaries.
+2. Assign every result or Forum observation used in a comparison to a cooldown. Prefer an explicit `cooldown_id`; when it is absent, infer membership only from the chip association and timestamp boundaries, and label it as inferred.
+3. Do not describe values from different cooldowns as one continuous degradation, recovery, or before/after trend. Partition the evidence by cooldown first. Cross-cooldown comparison is allowed only when it is explicitly identified as such.
+4. State plainly whether the compared evidence comes from the same cooldown, different cooldowns, or an unresolved cooldown context. Include the cooldown IDs in the report and in Forum evidence replies when relevant.
+5. Same cooldown does not guarantee identical measurement conditions. If cabling, attenuation, instruments, or wiring may have changed, inspect `qdash_get_cooldown_wiring` with history or `qdash_list_cooldown_wiring_events`, then distinguish a cooldown boundary from an in-cooldown wiring change.
+6. Do not treat a temporary disconnect/reconnect as a new cooldown unless QDash records a new cooldown. Describe it as an in-cooldown wiring event and report whether the wiring was nominally restored.
+7. Prefer same-cooldown, temporally adjacent measurements for physical interpretation. Older-cooldown evidence may provide context but must not be used to explain a current-cooldown anomaly without an explicit caveat.
+
+Before publishing investigated evidence, verify that every date-based claim respects these rules.
+
 ## Generic timeseries comparison
 
 Use `qdash_compare_timeseries` when the investigation needs to align multiple
@@ -116,8 +120,8 @@ If `QDASH_BASE_URL` is set and no profile is specified, the tools default to env
 
 When the user wants to preserve an investigated observation in QDash forum/notes:
 
-1. Inspect the task result, task figure, timeseries/history, and related forum context first.
-2. Summarize the observation as evidence, not as an automatic calibration decision.
+1. Inspect the task result, task figure, timeseries/history, related Forum context, and cooldown membership first.
+2. Summarize the observation as evidence, not as an automatic calibration decision. State whether compared observations are from the same cooldown, and separate in-cooldown wiring changes from cooldown boundaries.
 3. Prefer replying to an existing target/coupling forum thread when one exists.
 4. Use `qdash_create_forum_evidence_reply` for task-result evidence so figures are embedded as QDash UI image blocks (`/api/executions/figure?path=...`) and visible in the forum.
 5. For locally generated analysis images, call `qdash_preview_forum_image_reply` first, show the exact paths and reply text, then use `qdash_create_forum_image_reply` only after explicit confirmation. Supported images are PNG, JPEG, GIF, and WebP up to 5 MB each.

package/skills/qdash-calibration-agent/SKILL.md

@@ -9,7 +9,7 @@ metadata:
   maturity: experimental
   safety_level: operational-write-gated
   default_mode: one-target-one-action
-  source_of_truth: pi-qdash skills until QDash task-knowledge operation is finalized
+  source_of_truth: procedures in pi-qdash skills; task physics and interpretation in qdash-task-knowledge
   preferred_qubit_recovery_recipe: CheckRabi -> CheckChevron -> Configure -> CheckRabi
   requires_confirmation_for:
     - agent session creation
@@ -26,28 +26,32 @@ metadata:
 
 # QDash Calibration Agent
 
-This skill defines how pi should behave as a conservative, confirmation-gated calibration execution agent. It should orchestrate safe operational steps after diagnosis. Long-lived physics/task knowledge may later move to QDash task-knowledge; detailed read-only diagnosis should live in dedicated diagnosis skills.
+This skill defines how pi should behave as a conservative, confirmation-gated calibration execution agent. It orchestrates safe operational steps after diagnosis. Task physics, expected results, and failure modes come from QDash task knowledge; this skill owns procedure and safety gates.
 
 ## Core principles
 
 - Work one target at a time: one qubit or one coupling per action/session when possible.
 - Diagnose before changing parameters.
-- Prefer read-only inspection first: dashboard, failed task results, history, figures, forum posts, and task knowledge when available.
+- Establish cooldown identity before interpreting history: partition evidence by `cooldown_id`, never present different cooldowns as one continuous trend, and distinguish cooldown boundaries from in-cooldown wiring changes.
+- Prefer read-only inspection first: dashboard, cooldowns and wiring events, failed task results, history, figures, forum posts, and task knowledge when available.
 - Use narrow agent session policies with the smallest allowed task/action/parameter scope.
 - Do not commit or apply parameter candidates until a validation task succeeds and the user explicitly confirms.
 - Avoid blind parameter sweeps. If two conservative probes fail, step back to a diagnostic task.
-- Record useful lessons as task-knowledge cases or as updates to this skill.
+- Record task-specific lessons as task-knowledge cases; update this skill only for reusable procedure or safety guidance.
 
 ## Standard workflow
 
 1. Establish context:
    - profile and chip
+   - active/relevant `cooldown_id` and its time boundaries via `qdash_list_cooldowns`
+   - any in-cooldown wiring changes relevant to the target
    - failed task(s)
    - qid/coupling_id
    - recent executions and open forum/issue context
 2. Read evidence:
    - `qdash_list_task_results`
    - `qdash_get_task_result`
+   - `qdash_get_task_knowledge` for every task whose result will be interpreted
    - `qdash_get_task_figures` when figures exist
    - forum posts for the target when relevant
 3. Make a one-step plan.
@@ -61,7 +65,7 @@ This skill defines how pi should behave as a conservative, confirmation-gated ca
 
 ### CheckRabi returns non-finite frequency, NaN, or low R²
 
-Do not repeatedly perturb `control_amplitude`, `readout_amplitude`, or `shots` without diagnosis.
+Read `CheckRabi` and `CheckChevron` with `qdash_get_task_knowledge` before interpreting the failure or proposing recovery. Do not repeatedly perturb parameters without diagnosis.
 
 Canonical recovery sequence:
 
@@ -78,26 +82,9 @@ Recommended sequence:
 5. If successful, inspect candidates and only then consider committing/applying parameters with explicit user confirmation.
 6. If still failing after `Configure`, request human review and inspect raw/figure data.
 
-Known successful pattern:
-
-- Q33 on mackerel / `144Qv1`, 2026-07-14:
-  - repeated `CheckRabi` failures with `non-finite frequency: nan`
-  - `CheckChevron` succeeded and estimated:
-    - `qubit_frequency = 4.186021437949582 GHz`
-    - `control_amplitude = 0.196626929963469 a.u.`
-  - `Configure` completed
-  - `CheckRabi` then completed with the CheckChevron estimates:
-    - `rabi_frequency = 12.664970037417886 MHz`
-    - `control_amplitude = 0.19406572753680693 a.u.`
-
 ### CheckChevron interpretation and suggestions
 
-If `CheckChevron` completes:
-
-- Clear vertex/fringes: use estimated `qubit_frequency` and `control_amplitude`, then run `Configure -> CheckRabi` for validation.
-- Faint fringes: suspect insufficient drive, readout fidelity, or initialization/readout contrast; suggest readout diagnostics before parameter commits.
-- No visible chevron: inspect readout path first (`CheckReadoutFrequency`, `ReadoutClassification`) or request human review.
-- Asymmetric/double chevron: suspect TLS, higher-level transitions, AC Stark shift, or frequency collision; avoid committing simple Rabi outputs without review.
+Read `CheckChevron` with `qdash_get_task_knowledge` before judging its figure, estimates, expected curve, or failure mode.
 
 If `CheckChevron` fails:
 
@@ -106,36 +93,11 @@ If `CheckChevron` fails:
 3. Classify the failure message and input/output parameters.
 4. Suggest the next diagnostic, but require user confirmation before another operational action.
 
-Common failed-Chevron suggestions:
-
-- `Qubit frequency too low/high`, boundary hit, or fitted frequency outside normal operating range:
-  - Treat the Chevron estimate as unsafe.
-  - Do not commit/apply candidates.
-  - Do not run `Configure -> CheckRabi` from this estimate.
-  - Suggest `CheckQubitSpectroscopy`, coarse frequency search review, or human figure review.
-- Abnormally large `coarse_control_amplitude`:
-  - Suspect the coarse search latched onto a wrong transition, poor readout contrast, or an invalid operating point.
-  - Suggest spectroscopy/readout diagnostics rather than stronger drive.
-- Failed fit but visually plausible chevron:
-  - Ask the user to inspect figures.
-  - Consider adjusted scan bounds only with explicit user guidance.
-- Faint/washed-out chevron:
-  - Suggest `ReadoutClassification`, `CheckReadoutFrequency`, and initialization/readout checks.
-
-Known failed pattern:
-
-- Q35 on mackerel / `144Qv1`, 2026-07-14:
-  - repeated `CheckRabi` failures with `non-finite frequency: nan`
-  - `CheckChevron` failed with `Qubit frequency too low for qid=35: 2.759894 GHz < 3.0 GHz`
-  - input `coarse_qubit_frequency = 2.894185298591617 GHz`
-  - input `coarse_control_amplitude = 0.5623413251903492 a.u.`
-  - Suggested action: stop, inspect figures, and investigate spectroscopy/coarse frequency/readout state before any Configure/Rabi retry.
+Use the returned task knowledge to choose the next diagnostic. Treat unsafe estimates as non-committable, stop before `Configure -> CheckRabi`, and require confirmation for any additional task.
 
 ### CheckT2Echo failures
 
-- Compare with recent `CheckT1` and `CheckRamsey`.
-- If `T2_echo` is much shorter than `2*T1`, suspect noise/refocusing issues.
-- Verify π/π/2 pulses before treating echo as a pure coherence problem.
+Read `CheckT2Echo`, `CheckT1`, and `CheckRamsey` with `qdash_get_task_knowledge`, then compare their recent results before choosing a diagnostic.
 
 ## Coupling / two-qubit recovery rules
 
@@ -150,9 +112,7 @@ For `ZX90InterleavedRandomizedBenchmarking` or two-qubit validation failures, do
 5. `CheckBellStateTomography`
 6. then RB validation
 
-Treat `completed` as execution status, not proof of quality. If Bell fidelity is low, IRB uncertainty is large, or coherence-limit fidelity is much higher than measured Bell/IRB fidelity, suspect ZX90 angle/phase/cancel/rotary calibration before blaming T1/T2.
-
-If CR rotation is weak, inspect qubit detuning/frequency collisions and coupling history before increasing CR amplitude.
+Treat `completed` as execution status, not proof of quality. Before interpreting Bell, tomography, coherence-limit, CR, ZX90, or IRB output, read each relevant task with `qdash_get_task_knowledge`; then correlate the returned criteria with figures and same-cooldown history.
 
 ## Session policy guidelines
 

package/skills/qdash-timeseries-diagnosis/SKILL.md

@@ -22,9 +22,12 @@ checks.
   move together. The sensor itself may be a proxy for an unmeasured actuator,
   vibration, electrical noise, magnetic noise, or control cycle.
 - Count observed cycles, not raw sample points, when judging periodic evidence.
+- Resolve cooldown boundaries before interpreting drift or shared periodicity. Analyze each cooldown separately by default; never smooth, interpolate, correlate, or fit a period across a cooldown boundary unless an explicit cross-cooldown comparison is intended and clearly reported.
 
 ## Workflow
 
+When a compared QDash series comes from a task-specific output, call `qdash_get_task_knowledge` for that task before assigning physical meaning to its values, expected behavior, or failure modes.
+
 ### 1. Fix the investigation scope
 
 Record the reusable scope with `/qdash-investigation-setup` when multiple
@@ -32,6 +35,8 @@ comparison passes are expected. The JSON context accepts arbitrary QDash
 series, CSV mappings, window/timezone, and transform defaults. Record:
 
 - QDash profile and chip
+- cooldown IDs and start/end boundaries from `qdash_list_cooldowns`
+- any in-cooldown wiring events that overlap the window
 - metrics and target IDs
 - tags
 - start/end timestamps
@@ -45,7 +50,9 @@ a timezone from the host machine.
 ### 2. Inspect source integrity
 
 Before comparing, use `qdash_inspect_timeseries_csv` for local files whose
-schema or time encoding is not already established. Then:
+schema or time encoding is not already established. Use `qdash_list_cooldowns`
+to split the requested window at cooldown boundaries, and inspect cooldown
+wiring events when hardware conditions may have changed. Then:
 
 - verify first/last timestamps and overlap
 - check source point counts and cadence

package/skills/qdash-two-qubit-calibration-diagnosis/SKILL.md

@@ -17,7 +17,8 @@ Use this skill when investigating coupling-level calibration quality, especially
 
 - Treat `completed` as execution status, not proof of calibration quality.
 - Diagnose from evidence before suggesting operational actions.
-- Prefer read-only tools first: `qdash_target_report`, `qdash_list_task_results`, `qdash_get_task_result`, `qdash_analyze_figure_json`, and `qdash_get_task_figures`.
+- Resolve cooldown membership before comparing calibrations or coherence limits. Keep different cooldowns separate, and distinguish a cooldown boundary from an in-cooldown wiring change.
+- Prefer read-only tools first: `qdash_list_cooldowns`, `qdash_target_report`, `qdash_list_task_results`, `qdash_get_task_result`, `qdash_analyze_figure_json`, and `qdash_get_task_figures`.
 - Do not rerun RB first when validation quality is suspicious. Walk back through prerequisites.
 - Do not commit or apply candidates without explicit user confirmation, and only after downstream validation.
 
@@ -25,8 +26,8 @@ Use this skill when investigating coupling-level calibration quality, especially
 
 For a coupling `cA-B`:
 
-1. Build context with `qdash_target_report` and recent task results for the coupling.
-2. Inspect the latest tasks in this chain:
+1. Build context with `qdash_list_cooldowns`, `qdash_target_report`, and recent task results for the coupling. Record the cooldown ID for each result and inspect wiring events when measurement conditions may have changed.
+2. Inspect the latest same-cooldown tasks in this chain by default, and call `qdash_get_task_knowledge` for each task before interpreting its outputs or figures:
    - `CheckCrossResonance`
    - `CreateZX90`
    - `CheckZX90`
@@ -45,51 +46,9 @@ For a coupling `cA-B`:
 
 ## Interpretation rules
 
-### Completed but low quality
+Use `qdash_get_task_knowledge` for `CheckCrossResonance`, `CheckZX90`, `CheckBellState`, `CheckBellStateTomography`, `Check2QGateCoherenceLimit`, and `ZX90InterleavedRandomizedBenchmarking` as applicable. Apply the returned expected-result descriptions, criteria, failure modes, and check questions to the measured outputs.
 
-Flag as suspicious when any of these hold:
-
-- Bell-state tomography fidelity is below ~0.8.
-- IRB fidelity has a large uncertainty/error bar, or `n_trials` is small.
-- Coherence-limit fidelity is high but Bell/IRB fidelity is much lower.
-- `CheckZX90` repeated-pulse traces do not show a stable/consistent response.
-- CR parameter generation succeeds but `cr_amplitude` is near saturation or `zx_rotation_rate` is very small.
-
-### Coherence limit gap
-
-If `two_qubit_gate_coherence_limit` is high but measured Bell/IRB fidelity is low, do not attribute the issue primarily to T1/T2. Suspect control/calibration issues such as:
-
-- ZX90 angle error
-- CR phase error
-- cancel-pulse amplitude/phase mismatch
-- rotary compensation mismatch
-- readout/classification contribution to validation figures
-
-### Bell tomography signals
-
-For a Bell target resembling `( |00> + |11> ) / sqrt(2)`:
-
-- Large `|10>` or `|01>` population suggests population/conditional-rotation error, not just dephasing.
-- Weak `|00><11|` coherence suggests phase, dephasing, or preparation error.
-- Large imaginary coherence can indicate phase-compensation error.
-
-Use the heatmap summaries from `qdash_analyze_figure_json` as numeric evidence. Do not overfit a single plot; correlate with `CheckZX90` and IRB.
-
-### CheckZX90 repeated-pulse signals
-
-Look for stable repeated-pulse behavior. Warnings include:
-
-- Large scatter or non-decaying erratic points after the first few repetitions.
-- Large first-step contrast followed by a non-zero offset.
-- Different qualitative behavior between control and target qubit plots.
-
-These symptoms point toward angle/phase/cancel/rotary issues and should be investigated before trusting IRB.
-
-### IRB caveats
-
-- A `completed` IRB with large error bar is weak evidence.
-- Small `n_trials` should be reported explicitly.
-- If Bell tomography is poor, do not use IRB alone as a pass signal.
+Treat `completed` only as execution status. Correlate task knowledge with `qdash_analyze_figure_json`, same-cooldown history, and adjacent validation tasks; do not overfit one plot or use IRB alone as a pass signal.
 
 ## Recommended action sequence
 
@@ -107,19 +66,4 @@ Inspect figures/results
 
 Each operational step requires explicit confirmation. Validate Bell/tomography before using IRB as the final quality signal.
 
-## Known case: mackerel 144Qv1 c48-50, 20260725-003
-
-Symptoms observed:
-
-- `CheckCrossResonance` completed with `zx_rotation_rate ~ 1.69e-3`.
-- `Check2QGateCoherenceLimit` reported ~0.978.
-- `CheckBellStateTomography` reported `bell_state_fidelity ~ 0.60`.
-- Bell tomography had high `|10>` component/population (~0.29) and non-ideal coherence.
-- `ZX90InterleavedRandomizedBenchmarking` completed with `zx90_gate_fidelity ~0.94` but large error (~0.087) and `n_trials=10`.
-- `CheckZX90` repeated-pulse traces were not clean/stable.
-
-Interpretation:
-
-- This is not primarily coherence-limited.
-- Suspect ZX90 angle/phase/cancel/rotary calibration quality.
-- Prefer walking back through `CheckCrossResonance -> CreateZX90 -> CheckZX90`, then validate with Bell tomography before trusting IRB.
+Historical postmortem cases belong in QDash task knowledge. Retrieve them through `qdash_get_task_knowledge` rather than encoding device-specific values in this procedural skill.