kenaz 0.0.0-stage → 0.3.2

package/core/dev/designs/EXPANDABLE_CARD_DESIGN_SPEC.md

@@ -0,0 +1,509 @@
+# 可展開卡片設計規範 (Expandable Card Design Spec)
+
+> **版本**: 1.0.0
+> **日期**: 2026-02-06
+> **作者**: Designer Agent
+> **關聯功能**: F-001（任務狀態牆）、F-003（優化提案區）
+> **關聯任務**: TASK_091、TASK_092、TASK_093、TASK_094
+
+---
+
+## 1. 設計概念與目標
+
+### 設計理念
+
+將 Dashboard 卡片從靜態展示升級為可交互的展開/折疊組件，讓用戶在保持概覽視角的同時，能按需查看任務或提案的完整詳情。遵循 **漸進式揭露（Progressive Disclosure）** 原則——默認呈現關鍵摘要，展開後顯示完整內容。
+
+### 設計目標
+
+1. **信息密度平衡**：折疊態精簡、展開態豐富
+2. **一致性**：所有卡片類型共用相同的展開交互模式
+3. **HUD 風格延續**：保持賽博朋克/終端機美學（Cyan 發光、深色背景）
+4. **無障礙性**：支援鍵盤操作和 Screen Reader
+
+---
+
+## 2. 交互設計
+
+### 2.1 觸發方式
+
+| 操作 | 行為 | 說明 |
+|------|------|------|
+| **點擊卡片任意位置** | 展開/折疊切換 | 整個卡片為可點擊區域 |
+| **點擊展開圖標** | 展開/折疊切換 | 明確的交互提示 |
+| **鍵盤 Enter/Space** | 展開/折疊切換 | 焦點在卡片時觸發 |
+| **鍵盤 Escape** | 折疊 | 僅在展開態生效 |
+| **Hover** | 顯示展開提示 | 圖標旋轉微動畫 |
+
+### 2.2 狀態定義
+
+```
+┌─────────────────────────────────────┐
+│  [折疊態 - Collapsed]               │
+│                                     │
+│  摘要信息 + 展開圖標 (▼)            │
+│  用戶看到：標題、優先級、Agent 標籤  │
+└─────────────────────────────────────┘
+          │ click / Enter
+          ▼
+┌─────────────────────────────────────┐
+│  [展開態 - Expanded]                │
+│                                     │
+│  摘要信息 + 折疊圖標 (▲)            │
+│  ─────────────────────              │
+│  詳細內容區域                       │
+│  （依賴關係、描述、文件列表等）      │
+└─────────────────────────────────────┘
+```
+
+### 2.3 行為規則
+
+- **單卡獨立展開**：多張卡片可同時展開，不互斥
+- **狀態不持久化**：頁面刷新後恢復折疊態
+- **列表滾動**：展開不會導致頁面跳轉，僅在卡片所在容器內擴展
+
+---
+
+## 3. 視覺設計
+
+### 3.1 折疊態（Collapsed）
+
+延續現有卡片樣式，無破壞性變更。
+
+**TaskCard 折疊態：**
+```
+┌──────────────────────────────────────┐
+│ ┌─┐                                 │
+│ │ │  TASK_091                    ▼   │
+│ └─┘  可展開卡片 UI 設計規範          │
+│       P1  │  designer  │  🔒 2 paths │
+└──────────────────────────────────────┘
+```
+
+**ProposalCard 折疊態：**
+```
+┌──────────────────────────────────────┐
+│ ▌ 💡 Performance Optimization    ▼   │
+│ ▌    Reduce bundle size by...        │
+│ ▌    P1  │  2 files  │  ~3h         │
+└──────────────────────────────────────┘
+```
+
+### 3.2 展開態（Expanded）
+
+展開後在卡片底部增加詳細內容區域，以分隔線區分。
+
+**TaskCard 展開態：**
+```
+┌──────────────────────────────────────┐
+│ ┌─┐                                 │
+│ │ │  TASK_091                    ▲   │
+│ └─┘  可展開卡片 UI 設計規範          │
+│       P1  │  designer  │  🔒 2 paths │
+│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
+│  📋 Description                      │
+│  設計 Dashboard 卡片展開/折疊的      │
+│  UI 規範和交互模式...                │
+│                                      │
+│  🔗 Dependencies                     │
+│  └─ TASK_090 ✅                      │
+│  └─ TASK_089 ✅                      │
+│                                      │
+│  📁 Scope Paths                      │
+│  └─ dashboard/src/components/ui/     │
+│  └─ dev/designs/                     │
+│                                      │
+│  ✅ Acceptance Criteria              │
+│  └─ 產出設計規範文件                 │
+│  └─ 包含展開/折疊狀態的視覺示意     │
+└──────────────────────────────────────┘
+```
+
+**ProposalCard 展開態：**
+```
+┌──────────────────────────────────────┐
+│ ▌ 💡 Performance Optimization    ▲   │
+│ ▌    Reduce bundle size by...        │
+│ ▌    P1  │  2 files  │  ~3h         │
+│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
+│  📝 Reason                           │
+│  The current bundle includes unused  │
+│  lodash methods that increase load   │
+│  time by 200ms...                    │
+│                                      │
+│  📁 Affected Files                   │
+│  └─ src/utils/helpers.ts             │
+│  └─ src/lib/api.ts                   │
+│  └─ package.json                     │
+│                                      │
+│  🔧 Suggested Changes               │
+│  [View Diff]                         │
+│                                      │
+│  ┌──────────┐  ┌──────────┐         │
+│  │ ✅ Accept │  │ ❌ Ignore │         │
+│  └──────────┘  └──────────┘         │
+└──────────────────────────────────────┘
+```
+
+### 3.3 展開圖標
+
+使用 `lucide-react` 的 `ChevronDown` 圖標：
+
+| 狀態 | 圖標 | 旋轉角度 |
+|------|------|----------|
+| 折疊 | `ChevronDown` | 0deg |
+| 展開 | `ChevronDown` | 180deg（通過 CSS rotate） |
+| Hover | `ChevronDown` | 微移 2px（translateY） |
+
+```css
+/* 展開圖標容器 */
+.expand-icon {
+  transition: transform 200ms ease-out;
+}
+
+.expand-icon[data-expanded="true"] {
+  transform: rotate(180deg);
+}
+```
+
+### 3.4 分隔線
+
+展開態的摘要與詳情之間使用虛線分隔：
+
+```css
+.expand-separator {
+  border-top: 1px dashed rgba(0, 255, 255, 0.2);
+  margin: 8px 0;
+}
+```
+
+---
+
+## 4. 動畫規範
+
+### 4.1 展開動畫
+
+使用 CSS `grid-template-rows` 技巧實現平滑高度動畫（比 `max-height` 更精確）：
+
+```css
+/* 容器 */
+.expandable-content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 250ms ease-out;
+}
+
+.expandable-content[data-expanded="true"] {
+  grid-template-rows: 1fr;
+}
+
+/* 內容包裹 */
+.expandable-content > .inner {
+  overflow: hidden;
+}
+```
+
+### 4.2 內容淡入
+
+展開時內容從透明淡入：
+
+```css
+.expandable-content .inner {
+  opacity: 0;
+  transition: opacity 200ms ease-out 50ms; /* 50ms delay */
+}
+
+.expandable-content[data-expanded="true"] .inner {
+  opacity: 1;
+}
+```
+
+### 4.3 動畫參數表
+
+| 屬性 | 值 | 說明 |
+|------|-----|------|
+| **展開時長** | 250ms | grid-template-rows transition |
+| **折疊時長** | 200ms | 略快於展開（感覺更靈敏） |
+| **緩動函數** | ease-out | 自然減速效果 |
+| **內容淡入延遲** | 50ms | 等容器開始展開後再淡入 |
+| **內容淡入時長** | 200ms | 與展開同步完成 |
+| **圖標旋轉** | 200ms ease-out | 與內容展開同步 |
+
+### 4.4 Tailwind CSS 類映射
+
+```
+展開容器:  grid transition-[grid-template-rows] duration-250 ease-out
+折疊態:    grid-rows-[0fr]
+展開態:    grid-rows-[1fr]
+內容包裹:  overflow-hidden
+內容淡入:  opacity-0 transition-opacity duration-200 delay-50
+內容顯示:  opacity-100
+圖標旋轉:  transition-transform duration-200 ease-out
+圖標展開:  rotate-180
+```
+
+---
+
+## 5. 佈局規範
+
+### 5.1 展開內容區域結構
+
+```tsx
+<div className="expandable-detail">
+  {/* Section: 帶圖標的區塊標題 */}
+  <div className="detail-section">
+    <div className="detail-section-header">
+      <Icon size={14} />
+      <span>Section Title</span>
+    </div>
+    <div className="detail-section-content">
+      {/* 具體內容 */}
+    </div>
+  </div>
+</div>
+```
+
+### 5.2 間距規範
+
+| 元素 | 間距 | Tailwind 類 |
+|------|------|-------------|
+| 分隔線上下 | 8px | `my-2` |
+| 區塊之間 | 12px | `space-y-3` |
+| 區塊標題與內容 | 4px | `mt-1` |
+| 區塊內左縮排 | 16px | `pl-4` |
+| 詳情區域 padding | 12px 上方 | `pt-3` |
+
+### 5.3 文字規範
+
+| 元素 | 大小 | 顏色 | Tailwind 類 |
+|------|------|------|-------------|
+| 區塊標題 | 12px | Cyan 60% | `text-xs text-cyan-400/60` |
+| 內容文字 | 13px | Slate 300 | `text-[13px] text-slate-300` |
+| 列表項目 | 12px | Slate 400 | `text-xs text-slate-400` |
+| 文件路徑 | 12px | Cyan 300 mono | `text-xs text-cyan-300 font-mono` |
+| 狀態標記 | 12px | 依狀態定色 | `text-xs` |
+
+---
+
+## 6. 響應式行為
+
+### 6.1 桌面（>= 1024px）
+
+- 卡片寬度跟隨容器
+- 展開內容完整顯示
+- 多列佈局中展開不影響其他列
+
+### 6.2 平板（768px - 1023px）
+
+- 卡片全寬
+- 展開內容完整顯示
+- 可能需要水平滾動查看長文件路徑
+
+### 6.3 手機（< 768px）
+
+- 卡片全寬
+- 展開內容使用較小字體（text-[11px]）
+- 文件路徑截斷顯示（truncate）
+- Accept/Ignore 按鈕改為全寬堆疊
+
+---
+
+## 7. 無障礙性 (Accessibility)
+
+### 7.1 ARIA 屬性
+
+```tsx
+<div
+  role="button"
+  tabIndex={0}
+  aria-expanded={isExpanded}
+  aria-controls={`detail-${id}`}
+  onKeyDown={handleKeyDown}
+>
+  {/* 摘要內容 */}
+  <ChevronDown aria-hidden="true" />
+</div>
+
+<div
+  id={`detail-${id}`}
+  role="region"
+  aria-labelledby={`header-${id}`}
+  hidden={!isExpanded}
+>
+  {/* 展開內容 */}
+</div>
+```
+
+### 7.2 鍵盤操作
+
+| 按鍵 | 行為 |
+|------|------|
+| `Enter` | 展開/折疊切換 |
+| `Space` | 展開/折疊切換 |
+| `Escape` | 折疊（僅展開態） |
+| `Tab` | 移動到下一個可聚焦元素 |
+
+### 7.3 Screen Reader
+
+- 折疊態播報：「TASK_091，可展開卡片 UI 設計規範，P1，已折疊，按 Enter 展開」
+- 展開態播報：「TASK_091，可展開卡片 UI 設計規範，P1，已展開」
+
+---
+
+## 8. 組件 API 設計
+
+### 8.1 ExpandableCard（通用組件）
+
+```tsx
+interface ExpandableCardProps {
+  /** 唯一 ID，用於 ARIA 和 key */
+  id: string;
+  /** 是否默認展開 */
+  defaultExpanded?: boolean;
+  /** 受控模式：展開狀態 */
+  expanded?: boolean;
+  /** 展開狀態變化回調 */
+  onExpandedChange?: (expanded: boolean) => void;
+  /** 卡片摘要區域（始終可見） */
+  children: React.ReactNode;
+  /** 展開後顯示的詳細內容 */
+  detail?: React.ReactNode;
+  /** 額外 className */
+  className?: string;
+  /** 是否使用 HUD 樣式 */
+  variant?: 'hud' | 'bordered';
+}
+```
+
+### 8.2 使用範例
+
+```tsx
+{/* TaskCard 用法 */}
+<ExpandableCard
+  id={`task-${task.id}`}
+  variant="hud"
+  detail={<TaskDetailContent task={task} />}
+>
+  <TaskCardSummary task={task} />
+</ExpandableCard>
+
+{/* ProposalCard 用法 */}
+<ExpandableCard
+  id={`proposal-${proposal.id}`}
+  variant="bordered"
+  detail={<ProposalDetailContent proposal={proposal} />}
+>
+  <ProposalCardSummary proposal={proposal} />
+</ExpandableCard>
+```
+
+---
+
+## 9. CSS 新增類定義
+
+以下 CSS 類需添加至 `globals.css`：
+
+```css
+/* ===== Expandable Card ===== */
+
+/* 展開容器 - 使用 grid 技巧實現平滑高度動畫 */
+.expandable-content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 250ms ease-out;
+}
+
+.expandable-content[data-state="open"] {
+  grid-template-rows: 1fr;
+}
+
+/* 折疊方向加速 */
+.expandable-content[data-state="closed"] {
+  transition-duration: 200ms;
+}
+
+/* 內容包裹 */
+.expandable-content > .expandable-inner {
+  overflow: hidden;
+}
+
+/* 內容淡入 */
+.expandable-inner > .expandable-detail {
+  opacity: 0;
+  transition: opacity 200ms ease-out 50ms;
+}
+
+.expandable-content[data-state="open"] > .expandable-inner > .expandable-detail {
+  opacity: 1;
+}
+
+/* 分隔線 */
+.expand-separator {
+  border-top: 1px dashed rgba(0, 255, 255, 0.2);
+}
+
+/* 展開圖標旋轉 */
+.expand-chevron {
+  transition: transform 200ms ease-out;
+}
+
+.expand-chevron[data-state="open"] {
+  transform: rotate(180deg);
+}
+
+/* 展開態卡片發光增強 */
+.hud-card[data-expanded="true"] {
+  border-color: rgba(0, 255, 255, 0.5);
+  box-shadow: 0 0 15px rgba(0, 255, 255, 0.15);
+}
+
+/* 詳情區塊標題 */
+.detail-section-header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: rgba(0, 255, 255, 0.6);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+/* 詳情區塊內容 */
+.detail-section-content {
+  margin-top: 4px;
+  padding-left: 16px;
+  font-size: 13px;
+  color: #cbd5e1; /* slate-300 */
+}
+```
+
+---
+
+## 10. 實作優先級與依賴
+
+```
+TASK_091 (本設計規範) ✅
+    └── TASK_092 (通用 ExpandableCard 組件)
+            ├── TASK_093 (TaskCard 詳細內容整合)
+            └── TASK_094 (ProposalCard 詳細內容整合)
+```
+
+### TASK_092 實作要點
+1. 建立 `dashboard/src/components/ui/expandable-card/ExpandableCard.tsx`
+2. 添加 CSS 類至 `globals.css`
+3. 使用 Radix UI 的 `Collapsible` 原語或自建（推薦自建以保持輕量）
+4. 支援 `variant="hud"` 和 `variant="bordered"` 兩種視覺樣式
+
+### TASK_093 實作要點
+1. 拆分 TaskCard 為 Summary + Detail
+2. TaskDetailContent 顯示：描述、依賴、Scope Paths、驗收標準
+3. 保持現有 TaskCard 的外觀完全不變（折疊態 = 當前樣式）
+
+### TASK_094 實作要點
+1. 拆分 ProposalCard 為 Summary + Detail
+2. ProposalDetailContent 顯示：完整理由、所有受影響文件、Diff 按鈕、操作按鈕
+3. 保持現有 ProposalCard 的外觀完全不變（折疊態 = 當前樣式）
+
+---
+
+*Generated by Designer Agent | 2026-02-06*

package/core/dev/jev-eval/ACTIVE_CORRECTION.md

@@ -0,0 +1,52 @@
+# Active Jev correction experiment
+
+Local implementation and verification: 2026-09-20. This is a user-authorized opt-in experiment, not a claim of validated model quality or an installer release.
+
+## Enable and disable
+
+In **Default Models**, use the single **Jev-assisted judgments** switch for the current project (TASK_1970). It controls correction detection and Thalamus context ranking together, defaults to OFF, and saves both `jevCorrectionEnabled` and `jevThalamusEnabled` in one atomic settings request. The runtime keeps these project-local fields for compatibility; it does not inherit them from the Kenaz core project. Partial legacy settings are displayed as mixed, and the next check enables both.
+
+Provide your own `TYPESAFE_API_KEY` in the environment used to launch Kenaz, then restart Kenaz and its workers after changing that environment. The UI reports key presence, not a successful authentication check. There is no key input or key storage in these settings. On Windows, TASK_1971 startup reads the saved user environment key from HKCU only when the process variable is absent, so an older parent terminal does not prevent loading it. An explicitly present process value always wins; existing workers still need relaunching to inherit changes. Users without a key retain the existing workflow, even if the enabled preference was saved.
+
+ON makes valid Jev results authoritative for correction classification on the selected messages: positives add correction and make it the primary signal; negatives remove correction. Other label values, their relative order, and existing translation text are preserved. Existing consumers that process only the primary signal consequently follow correction instead of another primary label on positive results. Jev is not a text-generation model and does not replace the Ansuz or dispatch model selection.
+
+OFF restores the existing workflow for **future** judgments. It does not erase or undo previously accumulated user-profile signals, expertise changes, or feedback. In-flight results are discarded if the flag is OFF when they return.
+
+The shared extraction function is called by ordinary Muninn observations, the incremental Muninn watcher, and manual `backfill-user-model.js` runs. Consequently, running a manual historical backfill with this project flag and a valid key can also send eligible historical messages to Jev. No such backfill was performed for this implementation. The flag is project-local, while the existing profile writer stores results in the cross-project `~/.kenaz/user_profile.json`. Jev correction classification is not currently connected to Thalamus stimulation or context ranking.
+
+## Execution and fallback
+
+The existing synchronous Muninn/Haiku translation and classification still runs first. Jev then overlays correction decisions using fixed model `jev-1.13.0` and experimental probability threshold **0.5**, which is not calibrated on human-reviewed historical cases. This integration does not establish a whole-workflow speedup.
+
+Each batch selects at most eight eligible recent user messages from a bounded scan. Each request contains only its target message and up to four preceding visible conversation entries; no later message is shared with earlier targets. Known credential patterns and generated instruction blocks are filtered before transmission. The combined worker input is capped at 32 KiB. Opting in sends this limited conversation context to TypeSafe.
+
+A hidden Node worker sends isolated requests concurrently, with a shared 800 ms network deadline including response bodies and a 1,500 ms outer process timeout. There are no retries or configurable endpoint redirects. Any selected request failure or invalid response retains the complete original classification. Missing configuration, OFF, or a missing/invalid key makes no Jev request. If Haiku fails but Jev succeeds, positive correction-only signals can be emitted without inventing a translation.
+
+## Local feedback
+
+- `<project>/.kenaz/jev/decisions.jsonl`: best-effort, size-limited decision metadata, including hashed message IDs, probabilities, original correction flags, changed flags, latency, and fallback reasons. It excludes message text, keys, headers, and provider error bodies.
+- `<project>/.kenaz/jev/feedback.jsonl`: up to 200 **Helpful / Incorrect judgment** feedback events, with timestamp, model, enabled preference, verdict, and feature scope. The unified control records `feature: all`; historical correction/Thalamus classifications are preserved, and missing historical feature means correction. These describe overall experience, not adjudicated labels for individual cases.
+
+These new records are not automatically uploaded. They do not change the pre-existing user-profile storage behavior. General feedback and disagreement with the baseline cannot be interpreted as accuracy measurements without case-level review.
+
+Settings requests validate the expected project. Writes preserve omitted fields, serialize concurrent updates, and replace files atomically. The frontend only displays acknowledged changes, discards old project responses, imposes a five-second request/body deadline, and does not automatically retry mutations whose acknowledgement may have been lost.
+
+## Verification and remaining limits
+
+Verified locally:
+
+- 16 runtime tests, including real `extractUserSignals` to `updateUserModel` integration against an isolated temporary profile; positive, negative, OFF, timeout, privacy, and fallback cases.
+- 54 existing research tests; combined Node run: **70/70**.
+- 13 frontend controller/SSR tests; full Dashboard TypeScript check passed.
+- 8 Rust settings tests, including actual temporary-file persistence, concurrent partial updates, explicit false, project/stale-write rejection, and feedback retention.
+- ESLint completed with zero errors and 31 style warnings; diff whitespace checks passed.
+- A real isolated Node worker without a key returned `missing_key` without network access.
+- Local HTTP rejection probes: status GET with a wrong project returned `409 project_mismatch`; models POST with a wrong project returned 409; invalid feedback verdict returned 422. These probes did not enable the feature or save feedback.
+
+No real historical messages were submitted to Jev during this implementation. The production adapter has not undergone a live model-quality evaluation, browser DOM interaction acceptance, or installed-build validation. Previous synthetic latency results are evidence for the earlier smoke requests, not a latency guarantee for this integrated workflow.
+
+Changes remain local and uncommitted; no installer was built or released. The packaging script `dashboard/scripts/kenaz-core-staging.js` stages Git-tracked files only. New runtime files must be included in the tracked release changes before packaging, or the optional adapter will be absent and Muninn will retain the baseline.
+
+Follow-up [packaging verification](PACKAGING_VERIFICATION.md) exercised the real staging function in an isolated candidate and passed staged-worker no-key and mocked decision checks. The real index still omits the untracked helper; this verification does not remove that release prerequisite or establish installed-build acceptance.
+
+See [evaluation status](EVALUATION_STATUS.md) for the unchanged quality evidence and historical-corpus limitations.

package/core/dev/jev-eval/ANNOTATION_GUIDE.md

@@ -0,0 +1,68 @@
+# Jev 評測資料與標註規則
+
+狀態：研究資料契約。內附合成案例由代理提出，未經獨立人工驗證，不能用來宣稱 Jev 在 Kenaz 的準確率或達成正式上線門檻。
+
+## 資料來源與審閱狀態
+
+`provenance.source` 為 `synthetic` 或 `real`；`provenance.annotation` 為 `agent_proposed` 或 `human_verified`。兩者是獨立維度：人檢查過的合成案例仍然是 synthetic，從真實對話取得但由模型標註的資料仍然是 agent_proposed。
+
+human_verified 必須有可追蹤的非空 reviewer 和 ISO reviewed_at。這些欄位只記錄審閱宣告，程式不能證明人真的審閱過。正式評測需要保存 review 記錄，不能批次改欄位來「通過」。
+
+原始資料保持在本地；評測集只放完成判斷所需的去識別片段。不要輸入帳號、金鑰、個資、未授權外送的商務內容或完整 private transcript。這個工具不自動抓取 live session，也不自動上傳現有 Synapse。
+
+## Correction：判斷是否修正目前理解
+
+正例：最新訊息明確更正先前的描述、假設、對象、環境、範圍或執行方向。需要同時看 `state.message`、目標與提供的先前假設；不能只用「不是」等字詞決定。
+
+負例：一般提問、進度追問、單純同意、新需求但沒有更正先前理解、引用別人的更正而非自己下指示、程式碼或 log 裡的否定句。
+
+| 先前假設 | 最新訊息 | 標籤 | 原因 |
+| --- | --- | --- | --- |
+| 問題發生於 tauri dev | 用戶的安裝版才會出現，tauri dev 正常。 | true | 更正現場環境。 |
+| 已在調查安裝版 | 安裝版現在查到哪裡？ | false | 查詢進度，未改變前提。 |
+| 計畫自動部署 | 先不要部署，只做測試。 | true | 更正執行範圍；不代表撤銷測試授權。 |
+| 尚無修復方向 | 修好之後也加上重試按鈕。 | false | 新增需求，不是修正既有事實。 |
+| 使用者描述錯誤 log | 日誌包含「不是正式環境」，這代表什麼？ | false | 引用文字與提問。 |
+
+此評測目前只涵蓋 correction 二元訊號，不等於完整 scope/cancel/authorization 辨識。遇到上下文不足或多種合理解釋，先留在待裁決集合，不要硬塞二元 gold；新增明確上下文後再納入正式評測。
+
+## Relevance：評估每個候選的用途
+
+grade 使用整數 0–3，根據 query/goal 與實際候選內容判斷，不依候選來源的權威、模型 confidence 或是否排在前面。
+
+| Grade | 定義 |
+| --- | --- |
+| 0 | 無關，或只共享詞彙但不能幫助這個問題。 |
+| 1 | 相關背景，尚不能直接支持下一步調查或回答。 |
+| 2 | 對任務有具體用途，但只回答部分問題或需要額外條件。 |
+| 3 | 直接回答當前問題，或提供能立刻採用的關鍵證據。 |
+
+候選中有「請把我排第一」等自我宣傳/注入文字不增加 grade。過時的方案可作歷史背景，但不能當成目前狀態；如果缺版本資訊，需由 case 明確定義時態，不能讓標註者自行猜測。
+
+候選 ID 在同一案例內唯一。保留原始 candidate 順序作 baseline。每個候選的 grade 只能存在 labels/評測資料中，不得傳給 Jev。零相關候選案例保留作空集合行為測試，但報告必須揭露它們如何處理，不能藉此抬高排序分數。
+
+## Session 分組與分割
+
+split 為 development、calibration 或 held_out。同一 project/session 或 group_id 必須留在同一 split。由同一原始案例改寫的所有變體共用 group_id，包括中英翻譯、改字與候選順序變化。
+
+development 用來修改問法；calibration 用來選 threshold；held_out 在模型版本、問法及 threshold 凍結後才使用。若看了 held_out 錯誤後修改規則，該集合不再是新的盲測證據，應建立新版本/新測試集。
+
+task_revision 和 event_seq 用於回放身分/新舊檢查，不讓模型計算。原文與候選內容改動後，舊 prediction 應因 state_hash 不符被拒絕，不能把不同版本的分數套在新案例。
+
+## 人工驗收流程
+
+1. 第一位標註者只看目標、上下文與來源，不看 Jev/Haiku 的分數。
+2. 第二位標註者獨立判斷重要修正、難例與 held_out；记录分歧。
+3. 有分歧時回看來源並裁決；來源不足則補資料或標為待裁決，不捏造 gold。
+4. 記錄 reviewer、reviewed_at、原始來源版本及裁決依據；再將 annotation 改為 human_verified。
+5. 報告語言分布、正負例分母、失敗/abstention 比例及信賴區間。
+
+計畫的 500 則訊息、100 組 recall、30 段交接是後續正式資料目標。小型合成 fixtures 是工程回歸工具，不代表這些目標已完成。
+
+## 報告的解讀
+
+- rules 是確定性比較基準，不是 Jev 的模擬準確度。
+- replay 是指定 prediction 的回放；其 latency 是錄製數值，不是本次網路測量。
+- live 才能產生本次供應商延遲；需標示模型實際版本、輸入長度、錯誤與冷熱連線。
+- accuracy/precision/recall 在成功回答子集上的數字必須搭配 coverage；不得隱藏未回答樣本。
+- `promotion_eligible` 在本原型固定為 false。正式升級必須另外審閱 held_out 與端到端任務結果。

package/core/dev/jev-eval/BASELINE_COMPARISON.md

@@ -0,0 +1,45 @@
+# Muninn 與 Jev 比較紀錄
+
+範圍：TASK_34 新增隔離的研究量測工具，不修改 production Muninn，也不執行記憶觀察、符號刺激或 user-model 更新。
+
+## 比較對象
+
+現行 `.formation/tools/muninn.js:translateAndClassifyMessages` 把訊息編號後，一次要求 Haiku 輸出 translated 欄位與七種標籤：correction、question、delegation、evidence_seeking、challenge、length_too_long、length_too_short。註解預期英文翻譯，但實際 PROMPT_HEADER 沒有明說目標語言；不能只憑欄位非空就判定符合英文契約。它不接收本評測集的 goal 或 assumptions。
+
+既有 Jev provider 每個案例以 goal、assumptions、message 提問，correction 是一個 Noul，其他用途是候選 Score。之前的 Jev 實測因此不能直接作為這個 Haiku 批次的同功能速度比。
+
+研究工具從現有 Muninn 檔案讀取函式，在 stubbed 模組環境擷取真實提示及解析流程，保留 source 與 prompt SHA-256。離線預設不呼叫 Claude；live 只接受 synthetic 資料，用明確指定的 CLI 執行檔，固定安全模式、無工具、無 session persistence、無自訂 hooks/MCP。不把來源函式原本的權限略過參數帶入測量。
+
+這保留了應用提示與解析邏輯，卻不包含正式環境的 hooks、啟動設定或記憶副作用，所以名稱為「隔離的 Muninn prompt 基準」，不是完整 production 延遲。
+
+## 驗收與度量
+
+- live 前先檢查資料來源；任何 real 案例使請求被拒絕，避免研究工具意外外送待審片段。
+- 檢查回傳的每個 idx 唯一、完整且順序正確；翻譯非空、標籤屬於已知集合。先檢查 raw 結構，不能靠現有解析器過濾未知標籤後假裝正常。
+- 記錄整批 wall time，不把整批時間除以筆數後叫作單筆 p50/p95。
+- 翻譯非空只代表欄位存在，並不代表翻譯正確。
+- 更正 confusion 只對目前 synthetic/agent_proposed 的暫定標籤計算，不當作獨立真人品質評估。
+- model metadata 以 CLI 實際回傳為準；若未提供，只能記錄請求的 haiku alias，不能自行宣稱確切模型版本。
+
+## 本機資料來源盤點
+
+這次只盤點專案 `.kenaz/transcripts`：找到一份 failed 任務 JSONL，1,070,252 bytes、897 筆可解析記錄，其中 22 筆具有 user role。沒有輸出原始內容、沒有外送。這不足以達成 500 則跨 session 資料，也不應把工具／系統注入訊息當成真實用戶意圖。
+
+擴充資料仍需確認多 session 來源、過濾系統注入與重複內容、去識別及人工覆核。未取得來源選擇前，維持已準備的 6 筆真實待審片段與 11 筆合成回歸案例。
+
+## 執行結果
+
+主代理獨立重跑完整套件，33/33 通過（新增 7 項）；離線預設成功擷取 8 筆合成訊息的原始提示與 parser 契約，metrics 為 null。另以真實待審 seed 執行 live CLI，確認在 subprocess 前以 synthetic_only 拒絕。
+
+兩次合成批次呼叫及一次最小診斷呼叫皆未取得有效回答。CLI exit=1、is_error=true，訊息為週額度已用完、重設時間顯示 4pm (Asia/Taipei)，已停止重試。CLI subtype 雖顯示 success，不能覆蓋 exit/is_error 的失敗事實。第一次約 1708ms 是失敗的整批流程耗時，不是 Haiku 模型推論延遲。
+
+因此 Haiku confusion、正確率、成功推論延遲均未計算；沒有 Jev/Haiku 加速倍數。詳見 [原始摘要](reports/muninn-baseline-2026-09-20.json)。
+
+可重跑命令（live 需要本機 Claude 登入與可用額度）：
+
+```powershell
+node dev/jev-eval/muninn-baseline.mjs
+node dev/jev-eval/muninn-baseline.mjs --live --claude-cli <本機Claude執行檔絕對路徑>
+```
+
+CLI 產生報告即可能 exit=0，即使 report.status 是 invalid_or_failed_subprocess；消費者必須同時檢查 status，不能只看程序成功。沒有輸出 raw prompt、回答或金鑰。promotion_eligible 維持 false，沒有 production 整合或安裝包驗收。額度恢復與多 session 來源確認後，才能繼續補齊這部分實測。