feat(agent-workspace): add notification anomaly reporting

Author: Jacobinwwey

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

@@ -613,6 +613,36 @@ Deliverables:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+### M7.20 (Now): Notification Anomaly Surfacing and Retention-Policy Governance (Lane Ops Bridge)
+
+Deliverables:
+
+- add bounded notification anomaly-report route for operator escalation hygiene review.
+- expose explicit retention-policy semantics instead of hiding them in implementation details.
+- keep anomaly synthesis deterministic and sourced from current notification trail state.
+
+#### M7.20 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with notification anomaly route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies?limit=...`.
+- [Done] expanded notification-policy governance output:
+  - `/triage/remediation/escalation/notification-policy` now includes bounded `retentionPolicy`.
+- [Done] added deterministic anomaly/retention helper stack:
+  - `getAgentWorkspaceDiagnosticsRemediationEscalationNotificationRetentionPolicy(...)`,
+  - `buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyReport(...)`.
+- [Done] anomaly synthesis now surfaces at least:
+  - suppression dominance over emitted deliveries,
+  - digest throttle backlog,
+  - stale-cleanup application when cleanup removed stale reminder records.
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now validates retention-policy payload and anomaly-report route semantics.
+  - `src/knowledge.api.contract.test.ts` now fail-fast checks notification-anomalies route contract.
+  - `src/agent_workspace.verification.contract.test.ts` + `scripts/verify-agent-workspace-runtime.js` now fail fast on anomaly/retention helper and route drift.
+- [Done] verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern "escalation notification anomaly surfacing and retention-policy 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.
@@ -622,4 +652,4 @@ Deliverables:
 
 ## Next Step
 
-Proceed to `/prompts:ce-plan` using this document as the source for `M7.20` decomposition (notification anomaly surfacing and retention-policy governance), while preserving M7 lane boundary constraints.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.21` decomposition (notification escalation SLOs and anomaly-threshold governance), while preserving M7 lane boundary constraints.

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

@@ -580,6 +580,25 @@ Execution anchor:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## Latest Mainline Increment (2026-04-16 M7.20 Notification Anomaly Surfacing and Retention-Policy Governance Lane)
+
+- Expanded `src/server.ts` with notification anomaly route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies?limit=...`.
+- Expanded notification governance payload:
+  - `/triage/remediation/escalation/notification-policy` now includes explicit `retentionPolicy` with bounded trail and digest-history semantics.
+- Added deterministic anomaly synthesis:
+  - suppression-dominates-delivery warning,
+  - digest-throttle-backlog info signal,
+  - stale-cleanup-applied warning when stale reminder records were pruned.
+- Expanded executable evidence:
+  - `src/server.migration.test.ts` now validates retention-policy payload and anomaly-report route semantics.
+- 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-anomalies route and retention/anomaly helper drift.
+- Verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification anomaly surfacing and retention-policy governance stay deterministic\"`
+  - `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 |
@@ -628,7 +647,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 integrated | M7.20: anomaly surfacing and retention-policy 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 integrated | M7.21: notification escalation SLOs and anomaly-threshold governance |
 
 ## Verification Baseline
 

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

@@ -582,6 +582,25 @@
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## 主线最新增量（2026-04-16 M7.20 通知异常浮现与 Retention Policy 治理链路）
+
+- 已在 `src/server.ts` 增加通知异常路由：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies?limit=...`。
+- 已扩展通知治理输出：
+  - `/triage/remediation/escalation/notification-policy` 现在输出显式 `retentionPolicy`，明确 trail 上界与 digest history 上界语义。
+- 已新增确定性异常合成：
+  - suppressed 数量压过 emitted 数量时输出 suppression dominance 告警，
+  - digest throttled 事件积压时输出 throttle backlog 信号，
+  - 发生陈旧 reminder 清理时输出 stale cleanup 信号。
+- 已补可执行证据：
+  - `src/server.migration.test.ts` 新增 retention-policy 载荷与 anomaly-report 路由语义断言。
+- 已加固 runtime 门禁：
+  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 notification-anomalies 路由与 retention/anomaly helper 的 fail-fast 断言。
+- 验证证据：
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"escalation notification anomaly surfacing and retention-policy governance stay deterministic\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
@@ -630,7 +649,7 @@
 | L2 检索层 | 可解释混合/向量检索 + 治理 | 分支规划增强中 | 主线当前为 file-backed 基线（`src/learning/store.ts`） | 待主线出现对应模块证据后再收敛 |
 | L3 学习层 | 掌握诊断 + 路径/会话闭环 | 分支增强中 | 主线部分集成 | 契约与集成一致性 |
 | L4 交互层 | agent 对话 + focus/path pane 运行时 | 分支已实现 | 主线 M1-M4 已落入基线 | 继续通过 typed contract 扩展动作面 |
-| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 + 交付日志可观测性 + 陈旧通知健康审计 | M7.20：异常通知浮现与 retention policy 治理 |
+| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 + 交付日志可观测性 + 陈旧通知健康审计 + 异常/retention 治理 | M7.21：通知升级 SLO 与异常阈值治理 |
 
 ## 验证基线
 

scripts/verify-agent-workspace-runtime.js

@@ -168,6 +168,10 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-health'),
     'Missing diagnostics remediation escalation notification health route in src/server.ts'
   );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies'),
+    'Missing diagnostics remediation escalation notification anomalies route in src/server.ts'
+  );
   assert(
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/digest'),
     'Missing diagnostics remediation escalation digest route in src/server.ts'
@@ -300,6 +304,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationHealthReport'),
     'Missing remediation escalation notification health helper in src/server.ts'
   );
+  assert(
+    serverSource.includes('getAgentWorkspaceDiagnosticsRemediationEscalationNotificationRetentionPolicy'),
+    'Missing remediation escalation notification retention policy helper in src/server.ts'
+  );
+  assert(
+    serverSource.includes('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyReport'),
+    'Missing remediation escalation notification anomaly report helper in src/server.ts'
+  );
   assert(
     serverSource.includes('applyAgentWorkspaceDiagnosticsRemediationEscalationReminderSuppressionPolicy'),
     'Missing remediation escalation reminder suppression policy helper in src/server.ts'
@@ -367,14 +379,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
       'diagnostics remediation policy drift route exists',
       'diagnostics remediation escalation route exists',
       'diagnostics remediation escalation SLA/reminder routes exist',
-      'diagnostics remediation escalation notification policy, log, health, and digest routes exist',
+      'diagnostics remediation escalation notification policy, log, health, anomaly, and digest routes exist',
       'diagnostics remediation escalation acknowledgement routes exist',
       'diagnostics remediation approval routes exist',
       'diagnostics triage remediation route exists',
       'diagnostics retention governance exists',
       'diagnostics alert-threshold governance helpers exist',
       'diagnostics threshold simulation, drift, remediation, escalation, and SLA helpers exist',
-      'diagnostics escalation notification, digest cadence, reminder suppression, delivery-log, and health helpers exist',
+      'diagnostics escalation notification, digest cadence, reminder suppression, delivery-log, health, and anomaly helpers exist',
       'diagnostics remediation policy and alarm helpers exist',
       'diagnostics threshold audit helpers exist',
       'diagnostics remediation approval trail helpers exist',

src/agent_workspace.verification.contract.test.ts

@@ -65,6 +65,7 @@ describe('agent workspace verification script contracts', () => {
     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');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/digest');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/acknowledge');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals');
@@ -96,6 +97,8 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationSummary');
     expect(runtimeSource).toContain('cleanupStaleAgentWorkspaceDiagnosticsRemediationEscalationNotificationTrail');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationHealthReport');
+    expect(runtimeSource).toContain('getAgentWorkspaceDiagnosticsRemediationEscalationNotificationRetentionPolicy');
+    expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationNotificationAnomalyReport');
     expect(runtimeSource).toContain('applyAgentWorkspaceDiagnosticsRemediationEscalationReminderSuppressionPolicy');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationEscalationGovernanceContext');
     expect(runtimeSource).toContain('acknowledgeAgentWorkspaceDiagnosticsRemediationEscalation');

src/knowledge.api.contract.test.ts

@@ -29,6 +29,7 @@ describe('Knowledge mastery API contract wiring', () => {
             '/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',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/digest',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/acknowledge',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals',

src/server.migration.test.ts

@@ -2448,6 +2448,131 @@ describe('server migration settings routes', () => {
     ).toBe(true);
   });
 
+  test('escalation notification anomaly surfacing and retention-policy governance stay deterministic', async () => {
+    const diagnosticsDir = path.join(runtimeDataDir, 'agent_workspace_diagnostics');
+    const escalationNotificationPath = path.join(diagnosticsDir, 'triage_remediation_escalation_notifications.v1.json');
+    await fs.promises.mkdir(diagnosticsDir, { recursive: true });
+    await fs.promises.writeFile(
+      escalationNotificationPath,
+      JSON.stringify(
+        [
+          {
+            notificationId: 'suppressed-1',
+            generatedAt: '2026-04-16T00:00:00.000Z',
+            channel: 'reminder',
+            status: 'suppressed',
+            escalationId: 'drift:approval-metadata-policy-drift',
+            reminderId: 'reminder:suppressed-1',
+            digestId: '',
+            severity: 'warning',
+            title: 'suppressed reminder',
+            reason: 'cooldown_active',
+            forceDispatch: false,
+            nextEligibleAt: '2026-04-16T06:00:00.000Z',
+            overdueHours: 5,
+            previousOverdueHours: 3,
+            currentOverdueHours: 5,
+            breaches: 0,
+            emittedReminders: 0,
+            suppressedReminders: 1,
+            runbookLinkIds: ['development-progress-dashboard']
+          },
+          {
+            notificationId: 'throttled-1',
+            generatedAt: '2026-04-16T01:00:00.000Z',
+            channel: 'digest',
+            status: 'throttled',
+            escalationId: '',
+            reminderId: '',
+            digestId: 'digest:throttled-1',
+            severity: '',
+            title: 'throttled digest',
+            reason: 'digest_cadence_active',
+            forceDispatch: false,
+            nextEligibleAt: '2026-04-16T02:00:00.000Z',
+            overdueHours: 0,
+            previousOverdueHours: 0,
+            currentOverdueHours: 0,
+            breaches: 2,
+            emittedReminders: 0,
+            suppressedReminders: 1,
+            runbookLinkIds: ['development-progress-dashboard']
+          },
+          {
+            notificationId: 'emitted-1',
+            generatedAt: '2026-04-15T23:00:00.000Z',
+            channel: 'digest',
+            status: 'emitted',
+            escalationId: '',
+            reminderId: '',
+            digestId: 'digest:emitted-1',
+            severity: '',
+            title: 'emitted digest',
+            reason: '',
+            forceDispatch: false,
+            nextEligibleAt: '',
+            overdueHours: 0,
+            previousOverdueHours: 0,
+            currentOverdueHours: 0,
+            breaches: 1,
+            emittedReminders: 1,
+            suppressedReminders: 0,
+            runbookLinkIds: ['development-progress-dashboard']
+          }
+        ],
+        null,
+        2
+      ),
+      'utf8'
+    );
+
+    const notificationPolicyResponse = await requestJson(
+      port,
+      'GET',
+      '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-policy'
+    );
+    expect(notificationPolicyResponse.status).toBe(200);
+    expect(notificationPolicyResponse.body.success).toBe(true);
+    expect(notificationPolicyResponse.body.retentionPolicy).toEqual(
+      expect.objectContaining({
+        maxEntries: expect.any(Number),
+        staleReminderPolicy: 'prune_inactive_escalation',
+        cleanupMode: expect.any(String),
+        channelBounds: expect.objectContaining({
+          digestHistory: expect.any(Number)
+        })
+      })
+    );
+
+    const anomaliesResponse = await requestJson(
+      port,
+      'GET',
+      '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/escalation/notification-anomalies?limit=10'
+    );
+    expect(anomaliesResponse.status).toBe(200);
+    expect(anomaliesResponse.body.success).toBe(true);
+    expect(anomaliesResponse.body.report).toEqual(
+      expect.objectContaining({
+        generatedAt: expect.any(String),
+        anomalies: expect.any(Array),
+        summary: expect.objectContaining({
+          total: expect.any(Number),
+          warning: expect.any(Number),
+          info: expect.any(Number)
+        })
+      })
+    );
+    expect(anomaliesResponse.body.report.summary.total).toBeGreaterThan(0);
+    expect(anomaliesResponse.body.report.anomalies).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          anomalyId: expect.stringMatching(/suppression_dominates_delivery|digest_throttle_backlog/),
+          runbookLinkIds: expect.arrayContaining(['development-progress-dashboard'])
+        })
+      ])
+    );
+  });
+
   test('server runtime path avoids synchronous filesystem APIs', () => {
     const serverSourcePath = path.join(__dirname, 'server.ts');
     const serverSource = fs.readFileSync(serverSourcePath, 'utf8');