feat(governance): add notification threshold override audit

Author: Jacobinwwey

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

@@ -673,6 +673,40 @@ Deliverables:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+### M7.22 (Now): Notification Threshold Overrides and Audit-Trail Governance (Lane Ops Bridge)
+
+Deliverables:
+
+- add file-backed notification-threshold override routes for operator governance updates.
+- expose bounded audit-trail review for override/reset actions with previous/next threshold snapshots.
+- keep notification-policy and notification-slo surfaces hydrated from persisted override state instead of implicit constant-only thresholds.
+
+#### M7.22 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with notification-threshold governance routes:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds`,
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds/audit?limit=...`.
+- [Done] added file-backed override + audit artifacts:
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notification_thresholds.v1.json`,
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notification_thresholds_audit.v1.json`.
+- [Done] notification governance now hydrates persisted overrides in current operator surfaces:
+  - `/triage/remediation/escalation/notification-policy` returns override-backed `anomalyThresholdPolicy`,
+  - `/triage/remediation/escalation/notification-slo` evaluates breach thresholds from persisted overrides.
+- [Done] override audit entries now capture:
+  - `previousThresholds`,
+  - `nextThresholds`,
+  - `resetToDefault`,
+  - `source` / `reason`,
+  - delta summaries for suppression count, throttled digest count, and suppressed-to-emitted ratio.
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now validates override POST/GET/reset semantics, SLO effect under overridden thresholds, audit route payloads, and persisted file contents.
+  - `src/knowledge.api.contract.test.ts`, `src/agent_workspace.verification.contract.test.ts`, and `scripts/verify-agent-workspace-runtime.js` now fail fast on notification-threshold route and helper drift.
+- [Done] verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern "escalation notification threshold overrides and audit-trail governance stay deterministic"`
+  - `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.
@@ -682,4 +716,4 @@ Deliverables:
 
 ## Next Step
 
-Proceed to `/prompts:ce-plan` using this document as the source for `M7.22` decomposition (notification threshold overrides and audit-trail governance), while preserving M7 lane boundary constraints.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.23` decomposition (notification-threshold rollback preview and drift-diff governance), while preserving M7 lane boundary constraints.

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

@@ -599,22 +599,29 @@ Execution anchor:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
-## Latest Mainline Increment (2026-04-16 M7.21 Notification Escalation SLOs and Anomaly-Threshold Governance Lane)
-
-- Expanded `src/server.ts` with notification SLO route:
-  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-slo?limit=...`.
-- Expanded notification governance payload:
-  - `/triage/remediation/escalation/notification-policy` now includes explicit `anomalyThresholdPolicy`.
-- Added deterministic notification SLO synthesis:
-  - suppression-count warning threshold,
-  - throttled-digest warning threshold,
-  - suppressed-to-emitted ratio warning threshold.
+## Latest Mainline Increment (2026-04-16 M7.22 Notification Threshold Overrides and Audit-Trail Governance Lane)
+
+- Expanded `src/server.ts` with notification-threshold governance routes:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds`,
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds/audit?limit=...`.
+- Added file-backed override governance artifacts:
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notification_thresholds.v1.json`,
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notification_thresholds_audit.v1.json`.
+- Hardened notification governance hydration:
+  - `/triage/remediation/escalation/notification-policy` now returns override-backed `anomalyThresholdPolicy`,
+  - `/triage/remediation/escalation/notification-slo` now evaluates breach thresholds from persisted overrides.
+- Added bounded audit-trail semantics:
+  - previous/next threshold snapshots,
+  - reset-to-default flag,
+  - operator `source` / `reason`,
+  - per-field delta summaries for suppression count, throttled digest count, and suppressed-to-emitted ratio.
 - Expanded executable evidence:
-  - `src/server.migration.test.ts` now validates anomaly-threshold policy payload and notification SLO route semantics.
+  - `src/server.migration.test.ts` now validates override POST/GET/reset semantics, SLO behavior under override, audit-route payloads, and persisted file contents.
 - 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 notification-slo route and anomaly-threshold/SLO helper drift.
+  - `src/knowledge.api.contract.test.ts`, `src/agent_workspace.verification.contract.test.ts`, and `scripts/verify-agent-workspace-runtime.js` now fail fast on notification-threshold route and helper drift.
 - Verification evidence:
-  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification SLOs and anomaly-threshold governance stay deterministic\"`
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification threshold overrides and audit-trail governance stay deterministic\"`
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
@@ -666,7 +673,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 + runbook automation/audit + adaptive simulation/remediation + remediation backtest/approval-gate + approval-policy hardening/regression-alarms + approval-policy drift/escalation + escalation acknowledgement lifecycle/audit + escalation SLA/reminder baseline + notification digest/suppression baseline + delivery-log observability + stale-cleanup health auditing + anomaly/retention governance + notification SLO governance integrated | M7.22: notification threshold overrides and audit-trail governance |
+| L5 Governance | runbook, diagnostics, replay/autonomy controls | Expanded in branch | Operator diagnostics persistence/triage/history/threshold governance + runbook automation/audit + adaptive simulation/remediation + remediation backtest/approval-gate + approval-policy hardening/regression-alarms + approval-policy drift/escalation + escalation acknowledgement lifecycle/audit + escalation SLA/reminder baseline + notification digest/suppression baseline + delivery-log observability + stale-cleanup health auditing + anomaly/retention governance + notification SLO governance + notification-threshold override/audit governance integrated | M7.23: notification-threshold rollback preview and drift-diff governance |
 
 ## Verification Baseline
 

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

@@ -601,22 +601,29 @@
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
-## 主线最新增量（2026-04-16 M7.21 通知升级 SLO 与异常阈值治理链路）
-
-- 已在 `src/server.ts` 增加通知 SLO 路由：
-  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-slo?limit=...`。
-- 已扩展通知治理输出：
-  - `/triage/remediation/escalation/notification-policy` 现在输出显式 `anomalyThresholdPolicy`。
-- 已新增确定性通知 SLO 合成：
-  - suppressed count 告警阈值，
-  - throttled digest 告警阈值，
-  - suppressed-to-emitted ratio 告警阈值。
+## 主线最新增量（2026-04-16 M7.22 通知阈值覆盖与审计轨迹治理链路）
+
+- 已在 `src/server.ts` 增加通知阈值治理路由：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds`，
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds`，
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds/audit?limit=...`。
+- 已补 file-backed 覆盖治理产物：
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notification_thresholds.v1.json`，
+  - `runtime_data/agent_workspace_diagnostics/triage_remediation_escalation_notification_thresholds_audit.v1.json`。
+- 已加固通知治理链路的覆盖态读取：
+  - `/triage/remediation/escalation/notification-policy` 现在返回基于持久化覆盖的 `anomalyThresholdPolicy`，
+  - `/triage/remediation/escalation/notification-slo` 现在基于持久化覆盖阈值计算 breach。
+- 已增加有界审计轨迹语义：
+  - `previousThresholds` / `nextThresholds` 快照，
+  - `resetToDefault` 标记，
+  - operator `source` / `reason`，
+  - suppression count、throttled digest count 与 suppressed-to-emitted ratio 的逐字段 delta 摘要。
 - 已补可执行证据：
-  - `src/server.migration.test.ts` 新增 anomaly-threshold policy 载荷与 notification SLO 路由语义断言。
+  - `src/server.migration.test.ts` 新增 override POST/GET/reset、覆盖后 SLO 行为、audit 路由语义与持久化文件内容断言。
 - 已加固 runtime 门禁：
-  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 notification-slo 路由与 anomaly-threshold/SLO helper 的 fail-fast 断言。
+  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 notification-threshold 路由与 helper 的 fail-fast 断言。
 - 验证证据：
-  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification SLOs and anomaly-threshold governance stay deterministic\"`
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification threshold overrides and audit-trail governance stay deterministic\"`
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
@@ -668,7 +675,7 @@
 | L2 检索层 | 可解释混合/向量检索 + 治理 | 分支规划增强中 | 主线当前为 file-backed 基线（`src/learning/store.ts`） | 待主线出现对应模块证据后再收敛 |
 | L3 学习层 | 掌握诊断 + 路径/会话闭环 | 分支增强中 | 主线部分集成 | 契约与集成一致性 |
 | L4 交互层 | agent 对话 + focus/path pane 运行时 | 分支已实现 | 主线 M1-M4 已落入基线 | 继续通过 typed contract 扩展动作面 |
-| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 + 交付日志可观测性 + 陈旧通知健康审计 + 异常/retention 治理 + 通知 SLO 治理 | M7.22：通知阈值覆盖与审计轨迹治理 |
+| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 + 交付日志可观测性 + 陈旧通知健康审计 + 异常/retention 治理 + 通知 SLO 治理 + 通知阈值覆盖/审计治理 | M7.23：通知阈值回滚预览与 drift-diff 治理 |
 
 ## 验证基线
 

scripts/verify-agent-workspace-runtime.js

@@ -156,6 +156,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/reminders'),
     'Missing diagnostics remediation escalation reminders route in src/server.ts'
   );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds'),
+    'Missing diagnostics remediation escalation notification-threshold route in src/server.ts'
+  );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds/audit'),
+    'Missing diagnostics remediation escalation notification-threshold audit route in src/server.ts'
+  );
   assert(
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy'),
     'Missing diagnostics remediation escalation notification policy route in src/server.ts'
@@ -316,6 +324,22 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('getAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyThresholdPolicy'),
     'Missing remediation escalation notification anomaly threshold helper in src/server.ts'
   );
+  assert(
+    serverSource.includes('readAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdPolicy'),
+    'Missing remediation escalation notification threshold reader in src/server.ts'
+  );
+  assert(
+    serverSource.includes('persistAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdPolicy'),
+    'Missing remediation escalation notification threshold writer in src/server.ts'
+  );
+  assert(
+    serverSource.includes('readAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdAuditTrail'),
+    'Missing remediation escalation notification threshold audit reader in src/server.ts'
+  );
+  assert(
+    serverSource.includes('appendAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdAuditEntry'),
+    'Missing remediation escalation notification threshold audit writer in src/server.ts'
+  );
   assert(
     serverSource.includes('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyReport'),
     'Missing remediation escalation notification anomaly report helper in src/server.ts'

src/agent_workspace.verification.contract.test.ts

@@ -62,6 +62,8 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/audit');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/sla');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/reminders');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds/audit');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-health');
@@ -101,6 +103,10 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('getAgentWorkspaceDiagnosticsRemediationEscalationNotificationRetentionPolicy');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyReport');
     expect(runtimeSource).toContain('getAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyThresholdPolicy');
+    expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdPolicy');
+    expect(runtimeSource).toContain('persistAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdPolicy');
+    expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdAuditTrail');
+    expect(runtimeSource).toContain('appendAgentWorkspaceDiagnosticsRemediationEscalationNotificationThresholdAuditEntry');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationSloReport');
     expect(runtimeSource).toContain('applyAgentWorkspaceDiagnosticsRemediationEscalationReminderSuppressionPolicy');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationGovernanceContext');

src/knowledge.api.contract.test.ts

@@ -26,6 +26,8 @@ describe('Knowledge mastery API contract wiring', () => {
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/audit',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/sla',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/reminders',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-thresholds/audit',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notifications',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-health',