@oqtopus-team/pi-qdash 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",

package/skills/qdash/SKILL.md

@@ -22,7 +22,7 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `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_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`
    - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
 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
@@ -107,4 +107,5 @@ When the user wants to preserve an investigated observation in QDash forum/notes
 - Use `qdash_investigate` for natural-language requests to investigate, compare, or understand a target or recent calibration; it is read-only and combines recent results with target, Forum, issue, and recommendation context.
 - Use `qdash_compare_calibration` when the user asks what changed between recent calibration experiments; treat differences as evidence, not automatic approval to commit/apply parameters.
 - Use `qdash_recent_calibration_figure` when the user asks to see recent experiment images without a task ID.
+- Use `qdash_analyze_figure_json` for read-only numeric summaries of Plotly JSON calibration figures; keep domain-specific interpretation in the matching skill.
 - Prefer summarizing large responses with counts, IDs, time ranges, and notable values.

package/skills/{qdash-calibration → qdash-calibration-agent}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: qdash-calibration
-description: Guide conservative autonomous QDash calibration workflows from pi. Use when the user asks to calibrate, tune, recover failed calibration tasks, run agent calibration sessions, or decide the next calibration action for qubits/couplings.
+name: qdash-calibration-agent
+description: Guide conservative confirmation-gated QDash calibration execution workflows from pi. Use when the user asks to calibrate, tune, recover failed calibration tasks, run agent calibration sessions, or decide the next calibration action for qubits/couplings.
 license: Apache-2.0
 compatibility: pi-coding-agent >=0.74, pi-qdash extension, QDash agent-session APIs
 metadata:
@@ -9,7 +9,7 @@ metadata:
   maturity: experimental
   safety_level: operational-write-gated
   default_mode: one-target-one-action
-  source_of_truth: pi-qdash skill until QDash task-knowledge operation is finalized
+  source_of_truth: pi-qdash skills until QDash task-knowledge operation is finalized
   preferred_qubit_recovery_recipe: CheckRabi -> CheckChevron -> Configure -> CheckRabi
   requires_confirmation_for:
     - agent session creation
@@ -26,7 +26,7 @@ metadata:
 
 # QDash Calibration Agent
 
-This skill defines how pi should behave as a conservative calibration agent. It is operational guidance for the agent; long-lived physics/task knowledge may later move to QDash task-knowledge, but until that process is settled, keep practical calibration recipes here.
+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.
 
 ## Core principles
 
@@ -139,6 +139,8 @@ Known failed pattern:
 
 ## Coupling / two-qubit recovery rules
 
+For detailed two-qubit quality diagnosis, use the `qdash-two-qubit-calibration-diagnosis` skill. Keep this section as the conservative operational rule set.
+
 For `ZX90InterleavedRandomizedBenchmarking` or two-qubit validation failures, do not rerun RB first. Walk back through prerequisites:
 
 1. `CheckCrossResonance`
@@ -148,6 +150,8 @@ 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.
 
 ## Session policy guidelines

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

@@ -0,0 +1,125 @@
+---
+name: qdash-two-qubit-calibration-diagnosis
+description: Diagnose QDash two-qubit calibration quality from CR, ZX90, Bell-state, tomography, coherence-limit, and IRB task results. Use when a coupling calibration completes but gate fidelity, Bell fidelity, or validation quality may be poor.
+license: Apache-2.0
+compatibility: pi-coding-agent >=0.74, pi-qdash extension
+metadata:
+  domain: quantum-calibration
+  safety_level: read-only-first-write-gated
+  preferred_validation_chain: CheckCrossResonance -> CreateZX90 -> CheckZX90 -> CheckBellState -> CheckBellStateTomography -> ZX90InterleavedRandomizedBenchmarking
+---
+
+# QDash Two-Qubit Calibration Diagnosis
+
+Use this skill when investigating coupling-level calibration quality, especially when tasks are `completed` but quality may be poor.
+
+## Principles
+
+- 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`.
+- 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.
+
+## Standard read-only investigation
+
+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:
+   - `CheckCrossResonance`
+   - `CreateZX90`
+   - `CheckZX90`
+   - `CheckBellState`
+   - `CheckBellStateTomography`
+   - `Check2QGateCoherenceLimit`
+   - `ZX90InterleavedRandomizedBenchmarking`
+3. Fetch task details and record:
+   - CR: `cr_amplitude`, `cr_phase`, `cancel_amplitude`, `cancel_phase`, `rotary_amplitude`, `zx_rotation_rate`
+   - ZX90: `zx90_gate_time`
+   - Bell tomography: `bell_state_fidelity`
+   - Coherence limit: `two_qubit_gate_coherence_limit`
+   - IRB: `zx90_gate_fidelity`, its error, `zx90_depolarizing_rate`, `n_trials`
+4. For JSON figures, use `qdash_analyze_figure_json` before manually reading raw Plotly JSON.
+5. Summarize symptoms, likely failure mode, and the next *read-only or confirmation-gated* step.
+
+## Interpretation rules
+
+### Completed but low quality
+
+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.
+
+## Recommended action sequence
+
+When validation quality is poor:
+
+```text
+Inspect figures/results
+-> CheckCrossResonance
+-> CreateZX90
+-> CheckZX90
+-> CheckBellState
+-> CheckBellStateTomography
+-> ZX90InterleavedRandomizedBenchmarking
+```
+
+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.