feat(agent-workspace): add runbook automation and threshold audit trail

Author: Jacobinwwey

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

@@ -333,6 +333,33 @@ Deliverables:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+### M7.10 (Now): Operator Runbook Automation and Threshold-Change Audit Trail (Lane Ops Bridge)
+
+Deliverables:
+
+- add operator runbook automation output surface based on triage and trend-history signals.
+- add threshold-change audit trail persistence and bounded query route for governance traceability.
+- ensure triage, history, and runbook routes expose deterministic linkage to active threshold policy.
+
+#### M7.10 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with runbook automation route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/runbook?window=...`.
+- [Done] expanded threshold-governance audit route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit?limit=...`.
+- [Done] landed bounded audit persistence under runtime data:
+  - `agent_workspace_diagnostics/triage_policy_audit.v1.json` now captures threshold-change source/reason, before/after values, and computed change deltas.
+- [Done] strengthened triage payload semantics:
+  - `/triage` and `/triage/history` now include automated runbook actions derived from risk buckets and replay trend direction.
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now validates runbook automation payloads, threshold-audit query semantics, and audit-file persistence,
+  - `src/knowledge.api.contract.test.ts` now fail-fast checks runbook/audit route contracts,
+  - `src/agent_workspace.verification.contract.test.ts` + `scripts/verify-agent-workspace-runtime.js` now fail fast on audit 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.
@@ -342,4 +369,4 @@ Deliverables:
 
 ## Next Step
 
-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.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.11` decomposition (adaptive threshold-policy simulation and auto-remediation guardrails), while preserving M7 lane boundary constraints.

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

@@ -386,6 +386,25 @@ Execution anchor:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## Latest Mainline Increment (2026-04-16 M7.10 Operator Runbook Automation and Threshold-Audit Governance Lane)
+
+- Expanded `src/server.ts` with operator runbook automation surface:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/runbook?window=...`.
+- Expanded threshold-governance audit surface:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit?limit=...`.
+- Added persisted audit artifact:
+  - `runtime_data/agent_workspace_diagnostics/triage_policy_audit.v1.json` now stores threshold-change source/reason, before/after snapshots, and computed delta summary.
+- Extended triage/history semantics:
+  - `/triage` and `/triage/history` now expose deterministic `runbookActions` derived from risk-bucket and replay-trend signals.
+- Expanded executable evidence:
+  - `src/server.migration.test.ts` now validates runbook payloads, audit query semantics, and audit-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 runbook/audit 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 |
@@ -394,7 +413,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+history+threshold 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+runbook automation+threshold audit trail (`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 |
 
@@ -434,7 +453,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/history/threshold governance 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 + runbook automation/audit baseline integrated | Expand adaptive policy simulation and CI evidence depth |
 
 ## Verification Baseline
 

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

@@ -388,6 +388,25 @@
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## 主线最新增量（2026-04-16 M7.10 运维 runbook 自动化与阈值审计治理链路）
+
+- 已在 `src/server.ts` 增加运维 runbook 自动化路由面：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/runbook?window=...`。
+- 已扩展阈值治理审计路由面：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit?limit=...`。
+- 已新增阈值变更审计持久化工件：
+  - `runtime_data/agent_workspace_diagnostics/triage_policy_audit.v1.json` 持久化阈值变更 source/reason、前后快照与 delta 摘要。
+- 已扩展 triage/history 输出语义：
+  - `/triage` 与 `/triage/history` 现输出基于风险分桶与 replay 趋势的 `runbookActions` 自动化建议。
+- 已补可执行证据：
+  - `src/server.migration.test.ts` 新增 runbook 输出、audit 查询语义与 audit 文件落盘断言。
+- 已加固 runtime 门禁：
+  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 runbook/audit 路由与 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`） | 集成状态 |
@@ -396,7 +415,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 持久化/分级/趋势历史/阈值治理 + runbook 自动化 + 阈值审计治理基线（`src/frontend/agent_workspace_runtime.js`、`src/server.ts`） | 部分集成 |
 | graphdb/ANN 底座收敛 | 先前文档存在分支导向结论 | 主线当前为 file-backed store 基线（`src/learning/store.ts`） | 主线未集成 |
 | Markdown 阅读器治理升级 | 分支已有规划与部分实现 | 主线为旧基线 | 部分集成 |
 
@@ -436,7 +455,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

@@ -112,10 +112,18 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     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/runbook'),
+    'Missing diagnostics triage runbook 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('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit'),
+    'Missing diagnostics triage thresholds audit route in src/server.ts'
+  );
   assert(
     serverSource.includes('cleanupStaleAgentWorkspaceDiagnosticsReports'),
     'Missing diagnostics retention cleanup helper in src/server.ts'
@@ -132,6 +140,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('persistAgentWorkspaceDiagnosticsAlertThresholds'),
     'Missing diagnostics triage threshold writer in src/server.ts'
   );
+  assert(
+    serverSource.includes('readAgentWorkspaceDiagnosticsThresholdAuditTrail'),
+    'Missing diagnostics threshold audit reader in src/server.ts'
+  );
+  assert(
+    serverSource.includes('appendAgentWorkspaceDiagnosticsThresholdAuditEntry'),
+    'Missing diagnostics threshold audit writer in src/server.ts'
+  );
   assert(
     runtimeSource.includes('persistDiagnosticsReport'),
     'Missing persistDiagnosticsReport runtime surface in src/frontend/agent_workspace_runtime.js'
@@ -149,9 +165,12 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
       'diagnostics report persistence routes exist',
       'diagnostics triage route exists',
       'diagnostics triage history route exists',
+      'diagnostics triage runbook route exists',
       'diagnostics triage threshold governance routes exist',
+      'diagnostics triage threshold audit route exists',
       'diagnostics retention governance exists',
       'diagnostics alert-threshold governance helpers exist',
+      'diagnostics threshold audit helpers exist',
       'runtime diagnostics persistence surface exists',
       'agent workspace contract test suite passes',
     ],

src/agent_workspace.verification.contract.test.ts

@@ -49,11 +49,15 @@ describe('agent workspace verification script contracts', () => {
     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/runbook');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit');
     expect(runtimeSource).toContain('cleanupStaleAgentWorkspaceDiagnosticsReports');
     expect(runtimeSource).toContain('AGENT_WORKSPACE_DIAGNOSTICS_MAX_ENTRIES');
     expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsAlertThresholds');
     expect(runtimeSource).toContain('persistAgentWorkspaceDiagnosticsAlertThresholds');
+    expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsThresholdAuditTrail');
+    expect(runtimeSource).toContain('appendAgentWorkspaceDiagnosticsThresholdAuditEntry');
     expect(runtimeSource).toContain('persistDiagnosticsReport');
     expect(browserSource).toContain('verifyAgentWorkspaceBrowser');
     expect(tauriSource).toContain('verifyAgentWorkspaceTauri');

src/knowledge.api.contract.test.ts

@@ -13,7 +13,9 @@ describe('Knowledge mastery API contract wiring', () => {
             '/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/runbook',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit',
             '/api/knowledge/operator/agent-workspace-diagnostics/report',
             '/api/knowledge/store/reload',
             '/api/knowledge/ingest',