feat(agent-workspace): harden approval policy and add remediation alarms

Author: Jacobinwwey

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

@@ -415,6 +415,34 @@ Deliverables:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+### M7.13 (Now): Approval-Policy Hardening and Remediation Trend-Regression Alarms (Lane Ops Bridge)
+
+Deliverables:
+
+- harden approval policy semantics for high-risk remediation strategies.
+- expose remediation approval-policy surface for operator observability.
+- add remediation trend-regression alarm surface driven by backtest deltas.
+
+#### M7.13 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with remediation approval-policy route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/policy`.
+- [Done] expanded `src/server.ts` with remediation alarm route:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/alarms?window=...&strategy=...`.
+- [Done] hardened approval policy behavior:
+  - aggressive remediation strategy now requires approval by policy,
+  - approval requests now enforce minimum `approvedBy` and `reason` lengths before recording.
+- [Done] expanded regression-alarm semantics:
+  - remediation backtest now emits deterministic alarm payloads (`critical`/`warning`/`info`) for high-risk/failure/replay-trend regression detection.
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now validates approval-policy route contract, short-reason block path, aggressive apply approval requirement, approval consume reuse block, and remediation alarm payload semantics,
+  - `src/knowledge.api.contract.test.ts` now fail-fast checks policy/alarm route contracts,
+  - `src/agent_workspace.verification.contract.test.ts` + `scripts/verify-agent-workspace-runtime.js` now fail fast on policy/alarm helper and 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|adaptive threshold simulation and remediation guardrails|remediation backtest and approval-gate flow|approval policy hardening and remediation trend-regression alarms"`
+  - `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.
@@ -424,4 +452,4 @@ Deliverables:
 
 ## Next Step
 
-Proceed to `/prompts:ce-plan` using this document as the source for `M7.13` decomposition (approval-policy hardening and remediation efficacy trend-regression alarms), while preserving M7 lane boundary constraints.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.14` decomposition (approval-policy drift detection and alarm-to-runbook escalation automation), while preserving M7 lane boundary constraints.

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

@@ -444,6 +444,26 @@ Execution anchor:
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## Latest Mainline Increment (2026-04-16 M7.13 Approval-Policy Hardening and Remediation Regression-Alarms Lane)
+
+- Expanded `src/server.ts` with remediation approval-policy surface:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/policy`.
+- Expanded `src/server.ts` with remediation regression-alarm surface:
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/alarms?window=...&strategy=...`.
+- Hardened approval-policy behavior:
+  - approval requests now enforce minimum `approvedBy` and `reason` lengths,
+  - aggressive remediation strategy now requires approval by policy before apply.
+- Extended remediation backtest semantics:
+  - backtest payload now emits deterministic `alarms` for high-risk/failure/replay-trend regressions and non-recommended candidates.
+- Expanded executable evidence:
+  - `src/server.migration.test.ts` now validates policy route semantics, short-reason approval block path, aggressive apply approval requirement, consumed-approval reuse block path, and alarm payload shape.
+- 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 policy/alarm routes 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|adaptive threshold simulation and remediation guardrails|remediation backtest and approval-gate flow|approval policy hardening and remediation trend-regression alarms\"`
+  - `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 |
@@ -492,7 +512,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 baseline integrated | Add approval-policy hardening and remediation trend-regression alarms |
+| 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 baseline integrated | Add approval-policy drift detection and alarm-to-runbook escalation automation |
 
 ## Verification Baseline
 

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

@@ -446,6 +446,26 @@
   - `npm run test:agent-workspace:contracts`
   - `npm run verify:agent-workspace:runtime`
 
+## 主线最新增量（2026-04-16 M7.13 批准策略硬化与修复趋势回归告警链路）
+
+- 已在 `src/server.ts` 增加修复批准策略可观测路由面：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/policy`。
+- 已在 `src/server.ts` 增加修复趋势回归告警路由面：
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/alarms?window=...&strategy=...`。
+- 已硬化批准策略行为：
+  - 批准请求新增 `approvedBy` / `reason` 最小长度校验，
+  - aggressive 策略 remediation apply 由策略默认强制批准门禁。
+- 已扩展 remediation backtest 语义：
+  - backtest 输出新增确定性 `alarms`，覆盖高风险回归、失败回归、replay 趋势回归与 non-recommended 候选告警。
+- 已补可执行证据：
+  - `src/server.migration.test.ts` 新增 policy 路由语义、short-reason 批准阻断、aggressive apply 强制批准、consumed approval 复用阻断与 alarm 载荷断言。
+- 已加固 runtime 门禁：
+  - `src/knowledge.api.contract.test.ts`、`src/agent_workspace.verification.contract.test.ts` 与 `scripts/verify-agent-workspace-runtime.js` 新增 policy/alarm 路由与 helper 的 fail-fast 断言。
+- 验证证据：
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"triage route summarizes replay risk|triage history and alert-threshold governance|adaptive threshold simulation and remediation guardrails|remediation backtest and approval-gate flow|approval policy hardening and remediation trend-regression alarms\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
@@ -494,7 +514,7 @@
 | L2 检索层 | 可解释混合/向量检索 + 治理 | 分支规划增强中 | 主线当前为 file-backed 基线（`src/learning/store.ts`） | 待主线出现对应模块证据后再收敛 |
 | L3 学习层 | 掌握诊断 + 路径/会话闭环 | 分支增强中 | 主线部分集成 | 契约与集成一致性 |
 | L4 交互层 | agent 对话 + focus/path pane 运行时 | 分支已实现 | 主线 M1-M4 已落入基线 | 继续通过 typed contract 扩展动作面 |
-| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁基线 | 增补批准策略硬化与修复趋势回归告警 |
+| L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警基线 | 增补批准策略漂移检测与告警到 runbook 升级自动化 |
 
 ## 验证基线
 

scripts/verify-agent-workspace-runtime.js

@@ -132,6 +132,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/backtest'),
     'Missing diagnostics remediation backtest route in src/server.ts'
   );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/alarms'),
+    'Missing diagnostics remediation alarms route in src/server.ts'
+  );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/policy'),
+    'Missing diagnostics remediation policy route in src/server.ts'
+  );
   assert(
     serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals'),
     'Missing diagnostics remediation approvals route in src/server.ts'
@@ -164,10 +172,22 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
     serverSource.includes('buildAgentWorkspaceDiagnosticsThresholdPolicySimulation'),
     'Missing diagnostics threshold policy simulation helper in src/server.ts'
   );
+  assert(
+    serverSource.includes('getAgentWorkspaceDiagnosticsRemediationApprovalPolicy'),
+    'Missing diagnostics remediation approval policy helper in src/server.ts'
+  );
+  assert(
+    serverSource.includes('isAgentWorkspaceDiagnosticsApprovalRequiredByPolicy'),
+    'Missing diagnostics remediation approval policy matcher in src/server.ts'
+  );
   assert(
     serverSource.includes('buildAgentWorkspaceDiagnosticsRemediationBacktest'),
     'Missing diagnostics remediation backtest helper in src/server.ts'
   );
+  assert(
+    serverSource.includes('buildAgentWorkspaceDiagnosticsRemediationBacktestAlarms'),
+    'Missing diagnostics remediation alarm builder in src/server.ts'
+  );
   assert(
     serverSource.includes('requestAgentWorkspaceDiagnosticsRemediationApproval'),
     'Missing diagnostics remediation approval-request helper in src/server.ts'
@@ -218,11 +238,14 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
       'diagnostics triage threshold simulation route exists',
       'diagnostics triage threshold audit route exists',
       'diagnostics remediation backtest route exists',
+      'diagnostics remediation alarm route exists',
+      'diagnostics remediation policy route exists',
       'diagnostics remediation approval routes exist',
       'diagnostics triage remediation route exists',
       'diagnostics retention governance exists',
       'diagnostics alert-threshold governance helpers exist',
       'diagnostics threshold simulation and remediation helpers exist',
+      'diagnostics remediation policy and alarm helpers exist',
       'diagnostics threshold audit helpers exist',
       'diagnostics remediation approval trail helpers exist',
       'runtime diagnostics persistence surface exists',

src/agent_workspace.verification.contract.test.ts

@@ -54,6 +54,8 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/simulate');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/backtest');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/alarms');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/policy');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approve');
     expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation');
@@ -62,7 +64,10 @@ describe('agent workspace verification script contracts', () => {
     expect(runtimeSource).toContain('readAgentWorkspaceDiagnosticsAlertThresholds');
     expect(runtimeSource).toContain('persistAgentWorkspaceDiagnosticsAlertThresholds');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsThresholdPolicySimulation');
+    expect(runtimeSource).toContain('getAgentWorkspaceDiagnosticsRemediationApprovalPolicy');
+    expect(runtimeSource).toContain('isAgentWorkspaceDiagnosticsApprovalRequiredByPolicy');
     expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationBacktest');
+    expect(runtimeSource).toContain('buildAgentWorkspaceDiagnosticsRemediationBacktestAlarms');
     expect(runtimeSource).toContain('requestAgentWorkspaceDiagnosticsRemediationApproval');
     expect(runtimeSource).toContain('executeAgentWorkspaceDiagnosticsAutoRemediation');
     expect(runtimeSource).toContain('consumeAgentWorkspaceDiagnosticsRemediationApproval');

src/knowledge.api.contract.test.ts

@@ -18,6 +18,8 @@ describe('Knowledge mastery API contract wiring', () => {
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/simulate',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/thresholds/audit',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/backtest',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/alarms',
+            '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/policy',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approvals',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation/approve',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage/remediation',