Cxk

docs/superpowers/plans/2026-06-11-trust-workbench-session-plan.md

@@ -0,0 +1,208 @@
+# Trust Workbench Session Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development (recommended) or executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Turn the existing Trust Center into a guided review workbench without adding a new top-level module or changing the semantics of existing review actions.
+
+**Architecture:** Keep the current `/api/trust/*` endpoints and enrich their existing payloads with deterministic derived fields. Split the Vue Trust Center into small subcomponents for session planning, progress, signals, risk explanation, and decision coaching.
+
+**Tech Stack:** Python/FastAPI/SQLite backend helpers, Vue 3 `<script setup lang="ts">`, TypeScript types, Node test runner, pytest, Vite build.
+
+---
+
+## File Structure
+
+- Modify `snapgraph/trust_center.py`: add derived risk reasons, trust signals, review focus, and decision options.
+- Modify `tests/test_trust_center.py`: assert deterministic derived fields and existing validation.
+- Modify `frontend/src/components/trustCenterTypes.ts`: add frontend types for derived trust fields and session mode.
+- Create `frontend/src/components/trustCenterCopy.ts`: centralize action labels, risk labels, and microcopy helpers.
+- Create `frontend/src/components/TrustSessionPlanner.vue`: session mode selector and next-step explanation.
+- Create `frontend/src/components/TrustReviewProgress.vue`: current session progress and selected-item summary.
+- Create `frontend/src/components/TrustReviewSignals.vue`: reusable compact signal chips.
+- Create `frontend/src/components/TrustRiskLens.vue`: focused explanation of why an item has risk.
+- Create `frontend/src/components/TrustDecisionCoach.vue`: decision guidance, local validation, and submit actions.
+- Modify `frontend/src/components/TrustCenterView.vue`: own local session mode and wire the new subcomponents.
+- Modify `frontend/src/components/TrustReviewInbox.vue`: render signal strip and mode-aware card copy.
+- Modify `frontend/src/components/TrustReviewDetail.vue`: use risk lens and decision coach while preserving `batchAction`.
+- Modify `frontend/src/components/TrustBatchActionBar.vue`: improve batch guidance but keep payload shape.
+- Modify `frontend/src/components/TrustOpenLoopPanel.vue`: add compact prioritization copy.
+- Modify `frontend/src/components/TrustDiagnosticsPanel.vue`: add clearer trust debt summary.
+- Modify `frontend/src/styles.css`: style new trust session, progress, signal, lens, and coach surfaces.
+- Modify `tests/trust_operations_ui.test.ts`: assert new components and CSS hooks.
+
+## Task 1: Backend Derived Fields
+
+**Files:**
+- Modify: `snapgraph/trust_center.py`
+- Test: `tests/test_trust_center.py`
+
+- [ ] Add a failing pytest case asserting each review item contains `risk_reasons`, `decision_options`, `review_focus`, and `trust_signals`.
+
+Run:
+
+```bash
+pytest tests/test_trust_center.py::test_trust_review_queue_exposes_session_decision_fields -q
+```
+
+Expected before implementation: fail because the fields are absent.
+
+- [ ] Implement deterministic helpers in `snapgraph/trust_center.py`:
+  - `_risk_reasons(source, risk, evidence_count)`
+  - `_decision_options(source, risk)`
+  - `_review_focus(source, risk, evidence_count)`
+  - `_trust_signals(source, risk, evidence_count, topic_refs)`
+
+- [ ] Attach those fields inside `_review_item`.
+
+- [ ] Run:
+
+```bash
+pytest tests/test_trust_center.py::test_trust_review_queue_exposes_session_decision_fields -q
+pytest tests/test_trust_center.py -q
+```
+
+- [ ] Commit:
+
+```bash
+git add snapgraph/trust_center.py tests/test_trust_center.py
+git commit -m "feat: enrich trust review decision fields"
+```
+
+## Task 2: Frontend Types And Copy Helpers
+
+**Files:**
+- Modify: `frontend/src/components/trustCenterTypes.ts`
+- Create: `frontend/src/components/trustCenterCopy.ts`
+- Test: `tests/trust_operations_ui.test.ts`
+
+- [ ] Add a failing Node test asserting the new session mode type and copy helper names exist.
+
+Run:
+
+```bash
+node --test tests/trust_operations_ui.test.ts
+```
+
+Expected before implementation: fail because the helper file and types are missing.
+
+- [ ] Add types:
+  - `TrustReviewSessionMode`
+  - `TrustDecisionOption`
+  - `TrustReviewFocus`
+  - `TrustSignals`
+
+- [ ] Add copy helpers:
+  - `riskToneLabel`
+  - `boundaryLabel`
+  - `reviewStatusLabel`
+  - `decisionActionLabel`
+  - `sessionModeLabel`
+  - `sessionModeDescription`
+  - `confidenceLabel`
+
+- [ ] Run:
+
+```bash
+node --test tests/trust_operations_ui.test.ts
+```
+
+- [ ] Commit:
+
+```bash
+git add frontend/src/components/trustCenterTypes.ts frontend/src/components/trustCenterCopy.ts tests/trust_operations_ui.test.ts
+git commit -m "feat: add trust workbench copy helpers"
+```
+
+## Task 3: Session Planner And Progress
+
+**Files:**
+- Create: `frontend/src/components/TrustSessionPlanner.vue`
+- Create: `frontend/src/components/TrustReviewProgress.vue`
+- Modify: `frontend/src/components/TrustCenterView.vue`
+- Modify: `frontend/src/styles.css`
+- Test: `tests/trust_operations_ui.test.ts`
+
+- [ ] Add failing Node assertions for `TrustSessionPlanner`, `TrustReviewProgress`, `trust-session-planner`, and `trust-review-progress`.
+- [ ] Implement mode selection inside `TrustCenterView.vue` with local `ref<TrustReviewSessionMode>('high-risk')`.
+- [ ] Filter/sort the visible review list by the selected mode while keeping the loaded backend payload unchanged.
+- [ ] Render planner above the batch bar and progress between planner and inbox.
+- [ ] Run Node UI tests.
+- [ ] Commit:
+
+```bash
+git add frontend/src/components/TrustSessionPlanner.vue frontend/src/components/TrustReviewProgress.vue frontend/src/components/TrustCenterView.vue frontend/src/styles.css tests/trust_operations_ui.test.ts
+git commit -m "feat: add trust review session planner"
+```
+
+## Task 4: Signals, Risk Lens, And Decision Coach
+
+**Files:**
+- Create: `frontend/src/components/TrustReviewSignals.vue`
+- Create: `frontend/src/components/TrustRiskLens.vue`
+- Create: `frontend/src/components/TrustDecisionCoach.vue`
+- Modify: `frontend/src/components/TrustReviewInbox.vue`
+- Modify: `frontend/src/components/TrustReviewDetail.vue`
+- Modify: `frontend/src/styles.css`
+- Test: `tests/trust_operations_ui.test.ts`
+
+- [ ] Add failing Node assertions for the new component names and CSS hooks.
+- [ ] Render `TrustReviewSignals` in inbox cards and detail brief.
+- [ ] Render `TrustRiskLens` in the detail panel before raw evidence disclosures.
+- [ ] Move single-item note/rewrite/action UI into `TrustDecisionCoach`.
+- [ ] Preserve emitted `TrustBatchPayload` shape exactly.
+- [ ] Run Node UI tests.
+- [ ] Commit:
+
+```bash
+git add frontend/src/components/TrustReviewSignals.vue frontend/src/components/TrustRiskLens.vue frontend/src/components/TrustDecisionCoach.vue frontend/src/components/TrustReviewInbox.vue frontend/src/components/TrustReviewDetail.vue frontend/src/styles.css tests/trust_operations_ui.test.ts
+git commit -m "feat: add trust decision coaching UI"
+```
+
+## Task 5: Secondary Panels And Final Verification
+
+**Files:**
+- Modify: `frontend/src/components/TrustBatchActionBar.vue`
+- Modify: `frontend/src/components/TrustOpenLoopPanel.vue`
+- Modify: `frontend/src/components/TrustDiagnosticsPanel.vue`
+- Modify: `frontend/src/styles.css`
+- Test: `tests/trust_operations_ui.test.ts`
+
+- [ ] Add concise secondary guidance to batch, open-loop, and diagnostics panels.
+- [ ] Add responsive CSS for session planner, signal chips, risk lens, and decision coach.
+- [ ] Run:
+
+```bash
+node --test tests/*.test.ts
+pytest -q
+python -m snapgraph.cli lint
+npm run build
+```
+
+- [ ] Restore generated static assets after build:
+
+```powershell
+git restore -- snapgraph/static
+$workspace = (Resolve-Path '.').Path
+$files = git ls-files --others --exclude-standard snapgraph/static/assets
+foreach ($file in $files) {
+  $resolved = (Resolve-Path -LiteralPath $file).Path
+  if (-not $resolved.StartsWith($workspace, [System.StringComparison]::OrdinalIgnoreCase)) {
+    throw "Refusing to remove outside workspace: $resolved"
+  }
+  Remove-Item -LiteralPath $resolved -Force
+}
+```
+
+- [ ] Commit:
+
+```bash
+git add frontend/src/components/TrustBatchActionBar.vue frontend/src/components/TrustOpenLoopPanel.vue frontend/src/components/TrustDiagnosticsPanel.vue frontend/src/styles.css tests/trust_operations_ui.test.ts
+git commit -m "feat: refine trust secondary guidance"
+```
+
+## Self-Review
+
+- Spec coverage: the tasks cover derived fields, session planning, progress, signals, risk explanation, decision coaching, secondary panels, tests, and verification.
+- Scope: all changes stay inside the Trust Center and existing trust endpoints.
+- API compatibility: existing endpoints and action payloads are preserved.
+- No placeholder tasks remain; each task names concrete files, commands, and commit boundaries.

docs/superpowers/specs/2026-06-11-trust-workbench-session-design.md

@@ -0,0 +1,108 @@
+# Trust Workbench 2.1 Session Design
+
+## Goal
+
+Trust Workbench 2.1 keeps the current Trust Center feature set intact while making the same review work feel more guided, lower pressure, and easier to finish. The user still reviews AI-inferred save reasons, inspects evidence, updates open loops, and checks diagnostics. The change is in the interaction model: the screen should help the user decide what to review first, why that item matters, what action is safest, and what changed after the decision.
+
+This is deliberately not a new top-level module. It is a deeper version of the existing trust module.
+
+## User Problem
+
+The current trust workbench reduced visual density, but a user can still feel uncertain about three things:
+
+- where to start when many items are waiting
+- what confidence, risk, evidence, open loops, and review status mean in practical terms
+- whether a confirmation, rewrite, rejection, or deferral is the right decision
+
+The design should preserve information depth while staging it across a review session.
+
+## Recommended Approach
+
+Use a "review session" layer inside the existing Trust Center:
+
+1. A compact session planner at the top lets the user choose a review mode, see the queue scope, and understand the next best action.
+2. Review cards expose richer but compact decision signals: trust boundary, risk reason, evidence count, open-loop pressure, and recommended action.
+3. The detail panel becomes a decision cockpit: brief, evidence, risk explanation, rewrite guidance, decision note, and action preview.
+4. A small progress/summary area shows what has been selected or acted on in the current session.
+5. Diagnostics and open loops remain secondary and progressively disclosed.
+
+This creates substantial code because the current components need richer typed view models, helper utilities, UI sections, tests, and styles, but it stays inside the existing module.
+
+## Non-Goals
+
+- Do not add a new top-level route or sidebar item.
+- Do not add a new database table for sessions.
+- Do not change the semantics of existing review actions.
+- Do not require a real LLM or external API.
+- Do not upload or store API keys.
+
+## Frontend Design
+
+Add new Trust Center subcomponents:
+
+- `TrustSessionPlanner.vue`: chooses review mode and explains the current session goal.
+- `TrustReviewProgress.vue`: summarizes selected count, high-priority remaining count, and suggested next step.
+- `TrustDecisionCoach.vue`: explains each action and validates rewrite/note intent before submit.
+- `TrustRiskLens.vue`: shows why a selected item is risky without forcing users to open all raw evidence.
+- `TrustReviewSignals.vue`: reusable compact signal strip for cards and detail panels.
+
+Existing components stay in place and become orchestrators:
+
+- `TrustCenterView.vue` owns session mode and passes derived context down.
+- `TrustReviewInbox.vue` renders richer cards and emits the same selection/review events.
+- `TrustReviewDetail.vue` uses coach/lens components while still emitting the existing `batchAction` payload.
+- `TrustBatchActionBar.vue`, `TrustOpenLoopPanel.vue`, and `TrustDiagnosticsPanel.vue` gain clearer microcopy and summary helpers.
+
+## Backend Design
+
+Keep existing endpoints and payloads. Add derived fields to review items where useful:
+
+- `risk_reasons`: human-readable reasons for risk level
+- `decision_options`: action labels, descriptions, and whether a rewrite is required
+- `review_focus`: the recommended next thing the user should inspect
+- `trust_signals`: normalized counts and booleans for frontend display
+
+These fields are computed from existing source, cognitive context, graph, lifecycle, and review data. They do not change stored data.
+
+## Data Flow
+
+The frontend continues to load:
+
+- `/api/trust/review`
+- `/api/trust/review/{source_id}`
+- `/api/trust/open-loops`
+- `/api/trust/diagnostics`
+
+The Trust Center builds a local session state:
+
+- selected mode: high risk, quick clear, open loops, or all
+- selected source ids
+- current focused source
+- local draft notes and rewrites
+
+Submitting still calls `/api/trust/review/batch` or `/api/trust/open-loops/{loop_id}`.
+
+## Error Handling
+
+- If no review item exists, the session planner shows an empty-state next step.
+- If rewrite is selected without text, the decision coach blocks submit locally and the backend still enforces the existing validation.
+- If diagnostics are missing, the UI uses neutral fallback text.
+- If a selected item disappears after refresh, the existing detail reset behavior remains.
+
+## Testing
+
+Add or expand tests for:
+
+- review payload exposes derived decision and signal fields
+- risk reasons are deterministic and match existing data
+- rewrite action remains blocked without replacement text
+- Trust Center renders session planner, progress, decision coach, risk lens, and signal strip
+- compact mode still uses progressive disclosure and mobile-safe layout
+
+## Success Criteria
+
+- The Trust module has more code because the review workflow is better decomposed and tested, not because logic is duplicated.
+- The user can review the same items with fewer context switches.
+- Information remains available but is staged by priority.
+- All existing trust API tests continue to pass.
+- Frontend build and lint/test commands remain green.

frontend/src/components/TrustBatchActionBar.vue

@@ -3,6 +3,7 @@
     <div>
       <span>批量审查</span>
       <strong>{{ sourceIds.length ? `${sourceIds.length} 条已选择` : '选择队列项后操作' }}</strong>
+      <p class="trust-batch-guidance">{{ batchGuidance }}</p>
     </div>
     <input
       v-model="note"
@@ -32,6 +33,11 @@ const emit = defineEmits<{
 
 const note = ref('')
 const disabled = computed(() => props.busy || !props.sourceIds.length)
+const batchGuidance = computed(() => {
+  if (!props.sourceIds.length) return '批量动作适合已经看过、判断比较确定的材料。'
+  if (props.sourceIds.length === 1) return '只有一条时也可以批量处理；拿不准就打开右侧单条审查。'
+  return '多条一起处理前，确认它们属于同一种判断。'
+})
 
 function submit(action: TrustBatchPayload['action']) {
   if (disabled.value) return