feat(agent-workspace): add triage trend history and threshold governance

Author: Jacobinwwey

docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md

@@ -305,6 +305,34 @@ Deliverables:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+### M7.9 (Now): Operator Triage Trend History and Alert-Threshold Governance (Lane Ops Bridge)
+
+Deliverables:
+
+- add operator triage trend-history surface with bounded time-window sampling.
+- add operator alert-threshold governance surface (read/write + persisted policy file + bounded normalization).
+- ensure triage summary and history outputs are driven by active threshold policy rather than fixed constants.
+
+#### M7.9 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with threshold-governed triage surfaces:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/history?window=...`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds`,
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds`.
+- [Done] landed persisted threshold governance under runtime data:
+  - `agent_workspace_diagnostics/triage_policy.v1.json` now stores replay-medium/high thresholds, failure-escalation rule, top-replay limit, and history-window defaults.
+- [Done] strengthened triage semantics:
+  - `/triage` now returns threshold-governed risk buckets and embedded history payload,
+  - `/triage/history` returns bounded trend points (`window`, `replayCandidateRateDelta`, risk-bucket counts, failure counts).
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now validates threshold updates, history-window behavior, reset-to-default, and policy-file persistence,
+  - `src/knowledge.api.contract.test.ts` now fail-fast checks history/threshold route contracts,
+  - `src/agent_workspace.verification.contract.test.ts` + `scripts/verify-agent-workspace-runtime.js` now fail fast on threshold governance helper/route drift.
+- [Done] verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern "triage route summarizes replay risk|triage history and alert-threshold governance"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## Success Criteria
 
 - CI failure mode that previously blocked the three agent-workspace suites is eliminated on mainline.
@@ -314,4 +342,4 @@ Deliverables:
 
 ## Next Step
 
-Proceed to `/prompts:ce-plan` using this document as the source for `M7.9` decomposition (operator triage trend history and alert-threshold governance), while preserving M7 lane boundary constraints.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.10` decomposition (operator runbook automation and threshold-change audit trail), while preserving M7 lane boundary constraints.

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -366,6 +366,26 @@ Execution anchor:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## Latest Mainline Increment (2026-04-16 M7.9 Operator Triage Trend History and Alert-Threshold Governance Lane)
+
+- Expanded `src/server.ts` with threshold-governed triage surfaces:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/history?window=...`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds`,
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds`.
+- Added persisted threshold governance artifact:
+  - `runtime_data/agent_workspace_diagnostics/triage_policy.v1.json` now stores replay-medium/high thresholds, failure-escalation rule, top-replay limit, and history-window defaults.
+- Extended triage semantics:
+  - `/triage` now returns threshold-governed risk summary plus embedded history payload,
+  - `/triage/history` now returns bounded trend points, risk-bucket distribution, failure counts, and replay-rate delta.
+- Expanded executable evidence:
+  - `src/server.migration.test.ts` now validates threshold updates, bounded history window behavior, default reset, and policy-file persistence.
+- Hardened runtime verification gate:
+  - `src/knowledge.api.contract.test.ts`, `src/agent_workspace.verification.contract.test.ts`, and `scripts/verify-agent-workspace-runtime.js` now fail fast on history/threshold route and helper drift.
+- Verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"triage route summarizes replay risk|triage history and alert-threshold governance\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## Mainline vs Working-Branch Snapshot (2026-04-14)
 
 | Capability Slice | Working Branch (`feat/learning-multi-tutor-adapter`) | Mainline (`origin/main`) | Integration Status |
@@ -374,7 +394,7 @@ Execution anchor:
 | Focus + learning-path side-by-side pane model | Implemented in branch UI/runtime | Dock coexistence baseline integrated (`styles.css`, `path_styles.css`, `path_app.js`) | Partially integrated |
 | Agent workspace contract parity suite | Implemented (`src/agent_workspace.contract.parity.test.ts`, `src/agent_workspace.frontend.test.ts`, `src/agent_workspace.locale.contract.test.ts`, `src/agent_workspace.tauri.contract.test.ts`) | Baseline parity suite integrated (`src/agent_workspace.contract.parity.test.ts`, `src/agent_workspace.frontend.test.ts`, `src/agent_workspace.runtime.integration.test.ts`) | Partially integrated |
 | Result-presentation allowlist/override fail-fast governance | Implemented in branch execution registry and parity tests | Integrated in M1 (`src/frontend/agent_workspace.js` + parity tests) | Baseline integrated |
-| Conversation turn stream/replay/operator diagnostics expansion | Implemented in branch routes/tests | Mainline has runtime snapshot+trend/index/export plus sidecar persistence+triage+bounded retention governance (`src/frontend/agent_workspace_runtime.js`, `src/server.ts`) | Partially integrated |
+| Conversation turn stream/replay/operator diagnostics expansion | Implemented in branch routes/tests | Mainline has runtime snapshot+trend/index/export plus sidecar persistence+triage+history+threshold governance (`src/frontend/agent_workspace_runtime.js`, `src/server.ts`) | Partially integrated |
 | Graphdb/ANN foundation hardening lane | Branch-oriented lane claims exist in prior docs | Mainline currently exposes file-backed store baseline (`src/learning/store.ts`) | Not integrated on mainline |
 | Markdown reader governance refactor lane | Planned and partially implemented in branch | Mainline baseline only | Partially integrated |
 
@@ -414,7 +434,7 @@ This dashboard aligns against the following requirement chain:
 | L2 Retrieval | explainable hybrid/vector retrieval + governance | Expanded in branch-oriented plans | Mainline file-backed baseline only (`src/learning/store.ts`) | Re-enter lane after concrete module evidence lands on mainline |
 | L3 Learning | mastery diagnostics + path/session loop | Expanded in branch | Partially integrated | Contract and integration parity |
 | L4 Interaction | agent conversation + focus/path pane runtime | Implemented in branch | M1-M4 baseline integrated on mainline | Expand capability surface via typed contract only |
-| L5 Governance | runbook, diagnostics, replay/autonomy controls | Expanded in branch | Operator diagnostics persistence/triage/retention baseline integrated | Expand operator runbook automation and CI evidence depth |
+| L5 Governance | runbook, diagnostics, replay/autonomy controls | Expanded in branch | Operator diagnostics persistence/triage/history/threshold governance baseline integrated | Expand operator runbook automation and CI evidence depth |
 
 ## Verification Baseline
 

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -368,6 +368,26 @@
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## 主线最新增量（2026-04-16 M7.9 运维分级趋势历史与阈值治理链路）
+
+- 已在 `src/server.ts` 增加阈值驱动的 triage 路由面：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/history?window=...`，
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds`，
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds`。
+- 已增加阈值治理持久化工件：
+  - `runtime_data/agent_workspace_diagnostics/triage_policy.v1.json` 持久化 replay 中/高阈值、失败升级策略、top-replay 限制与 history-window 默认值。
+- 已扩展 triage 语义：
+  - `/triage` 输出基于当前阈值策略计算的风险分桶，并内嵌 history 摘要，
+  - `/triage/history` 输出有界趋势点、风险分布、失败计数与 replay 比率变化量。
+- 已补可执行证据：
+  - `src/server.migration.test.ts` 新增阈值更新、有界窗口、重置默认、策略文件落盘断言。
+- 已加固 runtime 门禁：
+  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 history/threshold 路由与 helper 的 fail-fast 断言。
+- 验证证据：
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"triage route summarizes replay risk|triage history and alert-threshold governance\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
@@ -376,7 +396,7 @@
 | Focus + learning-path 并排 pane 模型 | 分支已实现 | 已落入 dock 并排基线（`styles.css`、`path_styles.css`、`path_app.js`） | 部分集成 |
 | Agent workspace 合同门禁测试 | 已实现（`src/agent_workspace.contract.parity.test.ts`、`src/agent_workspace.frontend.test.ts`、`src/agent_workspace.locale.contract.test.ts`、`src/agent_workspace.tauri.contract.test.ts`） | 已落入基线门禁（`src/agent_workspace.contract.parity.test.ts`、`src/agent_workspace.frontend.test.ts`、`src/agent_workspace.runtime.integration.test.ts`） | 部分集成 |
 | 结果呈现 allowlist/override fail-fast 治理 | 分支已实现 | M1 已集成（`src/frontend/agent_workspace.js` + parity tests） | 基线已集成 |
-| conversation turn 流式/重放/诊断扩展 | 分支已扩展 | 主线已落入 runtime snapshot+trend/index/export + sidecar 持久化/分级/有界保留治理基线（`src/frontend/agent_workspace_runtime.js`、`src/server.ts`） | 部分集成 |
+| conversation turn 流式/重放/诊断扩展 | 分支已扩展 | 主线已落入 runtime snapshot+trend/index/export + sidecar 持久化/分级/趋势历史/阈值治理基线（`src/frontend/agent_workspace_runtime.js`、`src/server.ts`） | 部分集成 |
 | graphdb/ANN 底座收敛 | 先前文档存在分支导向结论 | 主线当前为 file-backed store 基线（`src/learning/store.ts`） | 主线未集成 |
 | Markdown 阅读器治理升级 | 分支已有规划与部分实现 | 主线为旧基线 | 部分集成 |
 
@@ -416,7 +436,7 @@
 | L2 检索层 | 可解释混合/向量检索 + 治理 | 分支规划增强中 | 主线当前为 file-backed 基线（`src/learning/store.ts`） | 待主线出现对应模块证据后再收敛 |
 | L3 学习层 | 掌握诊断 + 路径/会话闭环 | 分支增强中 | 主线部分集成 | 契约与集成一致性 |
 | L4 交互层 | agent 对话 + focus/path pane 运行时 | 分支已实现 | 主线 M1-M4 已落入基线 | 继续通过 typed contract 扩展动作面 |
-| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/保留治理基线 | 扩展 runbook 自动化与 CI 证据深度 |
+| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理基线 | 扩展 runbook 自动化与 CI 证据深度 |
 
 ## 验证基线
 

scripts/verify-agent-workspace-runtime.js

@@ -108,6 +108,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage'),
     'Missing diagnostics report triage route in src/server.ts'
   );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/history'),
+    'Missing diagnostics triage history route in src/server.ts'
+  );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds'),
+    'Missing diagnostics triage thresholds route in src/server.ts'
+  );
   assert(
     serverSource.includes('cleanupStaleAgentWorkspaceDiagnosticsReports'),
     'Missing diagnostics retention cleanup helper in src/server.ts'
@@ -116,6 +124,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('AGENT_WORKSPACE_DIAGNOSTICS_MAX_ENTRIES'),
     'Missing diagnostics retention bound constant in src/server.ts'
   );
+  assert(
+    serverSource.includes('readAgentWorkspaceDiagnosticsAlertThresholds'),
+    'Missing diagnostics triage threshold reader in src/server.ts'
+  );
+  assert(
+    serverSource.includes('persistAgentWorkspaceDiagnosticsAlertThresholds'),
+    'Missing diagnostics triage threshold writer in src/server.ts'
+  );
   assert(
     runtimeSource.includes('persistDiagnosticsReport'),
     'Missing persistDiagnosticsReport runtime surface in src/frontend/agent_workspace_runtime.js'
@@ -132,7 +148,10 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
       'conversation route wiring exists',
       'diagnostics report persistence routes exist',
       'diagnostics triage route exists',
+      'diagnostics triage history route exists',
+      'diagnostics triage threshold governance routes exist',
       'diagnostics retention governance exists',
+      'diagnostics alert-threshold governance helpers exist',
       'runtime diagnostics persistence surface exists',
       'agent workspace contract test suite passes',
     ],

src/agent_workspace.verification.contract.test.ts

@@ -48,8 +48,12 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/index');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/latest');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/history');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds');
     expect(runtimeSource).toContain('cleanupStaleAgentWorkspaceDiagnosticsReports');
     expect(runtimeSource).toContain('AGENT_WORKSPACE_DIAGNOSTICS_MAX_ENTRIES');
+    expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsAlertThresholds');
+    expect(runtimeSource).toContain('persistAgentWorkspaceDiagnosticsAlertThresholds');
     expect(runtimeSource).toContain('persistDiagnosticsReport');
     expect(browserSource).toContain('verifyAgentWorkspaceBrowser');
     expect(tauriSource).toContain('verifyAgentWorkspaceTauri');

src/knowledge.api.contract.test.ts

@@ -12,6 +12,8 @@ describe('Knowledge mastery API contract wiring', () => {
             '/api/knowledge/operator/agent-workspace-diagnostics/index',
             '/api/knowledge/operator/agent-workspace-diagnostics/latest',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/history',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds',
             '/api/knowledge/operator/agent-workspace-diagnostics/report',
             '/api/knowledge/store/reload',
             '/api/knowledge/ingest',