feat(agent-workspace): guide correction follow-up from managed memory state

Jacobinwwey · Jacobinwwey · commit fa5ced5437fb · 2026-04-21T05:15:04.000-05:00
diff --git a/docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md b/docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md
@@ -453,14 +453,14 @@ Mitigation:
 This delivery path already replaced "generic conversation enhancement" and most of its early pane-contract phases are now integrated on `main`.
 The immediate remaining priority is no longer basic focus/path shell delivery.
 It is conversation-product hardening on top of the shipped shell.
+`M8.22` already closed the minimum correction-flow gap by turning missing managed-memory state into explicit next-step guidance.
 
 Priority order:
 
-1. correction-flow closure on top of managed-memory state visibility,
-2. operator-facing visibility for conversation-memory and correction actions,
-3. stronger focus-mode / learning-path action surfaces tied to the active conversation atom,
-4. only then deeper personalization work,
-5. markdown-reader improvements only when they clearly compound the same study loop.
+1. operator-facing visibility for conversation-memory and correction actions,
+2. stronger focus-mode / learning-path action surfaces tied to the active conversation atom,
+3. only then deeper personalization work,
+4. markdown-reader improvements only when they clearly compound the same study loop.
 
 ## Related Pages
 
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -18,9 +18,9 @@ Current top priority is not feature-count expansion.
 Current top priority is **conversation-product hardening on top of the already-green backend baseline**:
 
 - keep backend sufficiency as a standing decision gate rather than an active execution lane,
-- close the correction/product/operator gap exposed after `M8.20-M8.21`,
-- narrow the next budget to correction-flow closure, operator-facing visibility, and stronger focus/path action surfaces,
-- keep remote `main` CI interpretation evidence-based: latest `3a1926a` workflows are green.
+- keep closing the correction/product/operator gap exposed after `M8.20-M8.22`,
+- treat `M8.22` as the minimum correction-flow closure baseline and move the remaining near-term budget into operator-facing visibility and stronger focus/path action surfaces,
+- keep remote `main` CI interpretation evidence-based: the latest fully completed `main` workflow set (`3a1926a`) is green, and the newer `e73b5c6` push remains non-red with `Migration Gates` still running at refresh time.
 
 ## Current Mainline Snapshot (2026-04-21 M8.18)
 
@@ -106,6 +106,20 @@ Execution anchor:
   - backend targeted-read filter metadata,
   - runtime managed-memory state messaging for present vs missing managed keys.
 
+## Latest Mainline Increment (2026-04-21 M8.22 Correction Follow-Up Guidance Lane)
+
+- Converted targeted managed-memory state reads into explicit correction-flow guidance without widening backend scope:
+  - missing `conversation_note:{atomId}` now maps to the existing `Store Memory Note` action label,
+  - missing `conversation_correction:{atomId}` now maps to the existing `Record Correction` action label.
+- Kept the slice intentionally bounded:
+  - no new backend route, persistence model, or mutation contract was introduced,
+  - runtime guidance is derived from the already-landed `matchedKeys` / `missingKeys` state metadata.
+- Runtime assistant summaries now close the minimum next-step gap after managed-memory inspection:
+  - targeted reads report present vs missing managed keys,
+  - when managed state is missing, the assistant now tells the operator which existing correction-flow action should happen next.
+- Expanded regression coverage for:
+  - runtime managed-memory state messaging with explicit next-step guidance.
+
 ## Latest Mainline Increment (2026-04-14 M1 Baseline)
 
 - Added first `AgentConversationAPI` contract surface:
diff --git a/docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md b/docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md
@@ -244,8 +244,8 @@ Recommended next product order:
 
 1. conversation-product hardening:
    - extend explicit conversation memory APIs beyond the current snapshot/read/managed-key inspection and note/correction/eviction surface,
-   - first close correction / feedback flows on top of the newly landed present/missing managed-state visibility,
-   - then add operator-facing visibility for conversation-memory and correction actions,
+   - the minimum correction / feedback closure is now integrated through explicit next-step guidance on missing managed state,
+   - next add operator-facing visibility for conversation-memory and correction actions,
    - then harden stronger agent action surfaces around focus mode and learning path.
 2. markdown-reader improvement:
    - only when it clearly compounds knowledge review or focus-mode study loops.
diff --git a/docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md b/docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md
@@ -441,14 +441,14 @@
 这条交付链已经替代“泛化对话增强”，且其早期 pane-contract 阶段已在 `main` 集成。
 当前第一优先级已经不再是基础 focus/path 壳层交付，
 而是建立在该壳层之上的 conversation-product 加固。
+`M8.22` 已经通过“把缺失托管记忆状态转成显式下一步提示”补上最小 correction-flow 缺口。
 
 优先顺序：
 
-1. 围绕托管记忆状态可见性收口 correction-flow closure，
-2. 增加 conversation-memory / correction action 的 operator-facing visibility，
-3. 继续加固绑定当前会话 atom 的 focus-mode / learning-path action surface，
-4. 之后才进入更深的 personalization 工作，
-5. Markdown 阅读器提升只有在能明确复利同一学习闭环时才进入前列。
+1. 增加 conversation-memory / correction action 的 operator-facing visibility，
+2. 继续加固绑定当前会话 atom 的 focus-mode / learning-path action surface，
+3. 之后才进入更深的 personalization 工作，
+4. Markdown 阅读器提升只有在能明确复利同一学习闭环时才进入前列。
 
 ## 关联页面
 
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -18,9 +18,9 @@
 当前重心是 **建立在已转绿 backend 基线之上的 conversation-product 加固**：
 
 - 让 backend sufficiency 继续作为常驻 decision gate，而不是继续占用主动执行预算，
-- 收口 `M8.20-M8.21` 之后暴露出的 correction / product / operator 缺口，
-- 将下一段预算明确收敛到 correction-flow closure、operator-facing visibility 与更强的 focus/path action surface，
-- 远端 `main` CI 解释继续基于代码事实：当前 `3a1926a` 最新工作流为绿色。
+- 持续收口 `M8.20-M8.22` 之后暴露出的 correction / product / operator 缺口，
+- 将 `M8.22` 视作最小 correction-flow closure 基线，把剩余近端预算转向 operator-facing visibility 与更强的 focus/path action surface，
+- 远端 `main` CI 解释继续基于代码事实：最近一组已完整结束的 `main` 工作流（`3a1926a`）为绿色，而更新的 `e73b5c6` 推送在刷新时也保持非红，仅 `Migration Gates` 仍在执行。
 
 ## 当前主线快照（2026-04-21 M8.18）
 
@@ -106,6 +106,20 @@
   - backend 定向读取过滤元数据，
   - runtime 托管记忆状态消息对“已存在/缺失”键的断言。
 
+## 主线最新增量（2026-04-21 M8.22 Correction Follow-Up Guidance 链路）
+
+- 已在不扩大 backend 范围的前提下，把定向托管记忆状态读取升级为显式 correction-flow 提示：
+  - 缺失 `conversation_note:{atomId}` 时，运行时会映射到现有 `Store Memory Note` 动作标签，
+  - 缺失 `conversation_correction:{atomId}` 时，运行时会映射到现有 `Record Correction` 动作标签。
+- 范围仍然刻意保持收敛：
+  - 没有新增 backend 路由、持久化模型或 mutation contract，
+  - 当前提示完全基于已经落地的 `matchedKeys` / `missingKeys` 状态元数据推导。
+- runtime assistant 摘要现在补上了托管记忆检查后的最小下一步缺口：
+  - 定向读取继续报告已存在 / 缺失的托管 key，
+  - 一旦托管状态缺失，assistant 会明确指出下一步应执行的既有 correction-flow 动作。
+- 回归覆盖同步扩展到：
+  - runtime 托管记忆状态消息对显式下一步提示的断言。
+
 ## 主线最新增量（2026-04-14 M1 基线）
 
 - 已新增第一版 `AgentConversationAPI` 合同面：
diff --git a/docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md b/docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md
@@ -243,9 +243,9 @@
 
 1. conversation-product 加固：
    - 在当前 snapshot/read/托管 key 检查与 note/correction/eviction 能力之上继续扩展显式 conversation memory API，
-   - 先围绕刚落地的“已存在/缺失托管状态可见性”收口 correction / feedback 流程，
-   - 再补 conversation-memory / correction action 的 operator-facing visibility，
-   - 最后再继续加固围绕 focus mode 与 learning path 的 agent action surface。
+   - 最小 correction / feedback 收口已经通过“缺失托管状态 -> 显式下一步提示”集成到主线，
+   - 下一步补 conversation-memory / correction action 的 operator-facing visibility，
+   - 之后再继续加固围绕 focus mode 与 learning path 的 agent action surface。
 2. markdown reader 提升：
    - 只有在它能明确加强知识 review 或 focus-mode 学习闭环时，再提升优先级。
 
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -1865,6 +1865,7 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('session/read');
         expect(messages.textContent || '').toContain('present note');
         expect(messages.textContent || '').toContain('missing correction');
+        expect(messages.textContent || '').toContain('next Record Correction');
     });
 
     test('executes memory write capability, prompts for note text, and persists deterministic key', async () => {
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -197,6 +197,30 @@
             return labels.length ? labels.join(', ') : 'none';
         }
 
+        function summarizeManagedMemoryFollowUpActions(keys) {
+            const labels = [];
+            resolveStringArray(keys).forEach((key) => {
+                if (key.startsWith('conversation_note:')) {
+                    labels.push(
+                        getI18nText(
+                            'agentWorkspace.actions.writeMemoryNote',
+                            'Store Memory Note'
+                        )
+                    );
+                    return;
+                }
+                if (key.startsWith('conversation_correction:')) {
+                    labels.push(
+                        getI18nText(
+                            'agentWorkspace.actions.recordMemoryCorrection',
+                            'Record Correction'
+                        )
+                    );
+                }
+            });
+            return Array.from(new Set(labels)).join(', ');
+        }
+
         function resolveMisconceptionTopK(rawTopK, fallback) {
             const numericTopK = Number(rawTopK);
             const numericFallback = Number(fallback);
@@ -1501,6 +1525,7 @@
                     const targetedMatchKeys = resolveStringArray(filter && filter.matchKeys);
                     const matchedKeys = resolveStringArray(filter && filter.matchedKeys);
                     const missingKeys = resolveStringArray(filter && filter.missingKeys);
+                    const followUpActionsSummary = summarizeManagedMemoryFollowUpActions(missingKeys);
                     if (operation === 'write') {
                         appendMessage(
                             'assistant',
@@ -1542,13 +1567,18 @@
                         appendMessage(
                             'assistant',
                             getI18nText(
-                                'agentWorkspace.messages.memoryTargetedReadLoaded',
-                                `Memory targeted read loaded (${layer}/${operation}): present ${summarizeMemoryKeyLabels(matchedKeys)}, missing ${summarizeMemoryKeyLabels(missingKeys)}, totals session ${Number.isFinite(sessionCount) ? sessionCount : 0}, unit ${Number.isFinite(unitCount) ? unitCount : 0}, long-term ${Number.isFinite(longTermCount) ? longTermCount : 0}.`,
+                                followUpActionsSummary
+                                    ? 'agentWorkspace.messages.memoryTargetedReadLoadedWithNext'
+                                    : 'agentWorkspace.messages.memoryTargetedReadLoaded',
+                                followUpActionsSummary
+                                    ? `Memory targeted read loaded (${layer}/${operation}): present ${summarizeMemoryKeyLabels(matchedKeys)}, missing ${summarizeMemoryKeyLabels(missingKeys)}, next ${followUpActionsSummary}, totals session ${Number.isFinite(sessionCount) ? sessionCount : 0}, unit ${Number.isFinite(unitCount) ? unitCount : 0}, long-term ${Number.isFinite(longTermCount) ? longTermCount : 0}.`
+                                    : `Memory targeted read loaded (${layer}/${operation}): present ${summarizeMemoryKeyLabels(matchedKeys)}, missing ${summarizeMemoryKeyLabels(missingKeys)}, totals session ${Number.isFinite(sessionCount) ? sessionCount : 0}, unit ${Number.isFinite(unitCount) ? unitCount : 0}, long-term ${Number.isFinite(longTermCount) ? longTermCount : 0}.`,
                                 {
                                     layer,
                                     operation,
                                     matchedKeysSummary: summarizeMemoryKeyLabels(matchedKeys),
                                     missingKeysSummary: summarizeMemoryKeyLabels(missingKeys),
+                                    nextActionsSummary: followUpActionsSummary,
                                     sessionCount: Number.isFinite(sessionCount) ? sessionCount : 0,
                                     unitCount: Number.isFinite(unitCount) ? unitCount : 0,
                                     longTermCount: Number.isFinite(longTermCount) ? longTermCount : 0,
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -295,7 +295,8 @@
       "memoryWriteLoaded": "Memory updated ({layer}/{operation}): wrote {mutatedCount} entry, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}.",
       "memoryEvictLoaded": "Memory eviction completed ({layer}/{operation}): removed {evictedCount} entries, targeted keys {removedKeysCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}.",
       "memoryPolicyLoaded": "Memory snapshot loaded ({layer}/{operation}): {entriesCount} entries, evicted {evictedCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}, recommended {recommendedActionsCount} actions.",
-      "memoryTargetedReadLoaded": "Memory targeted read loaded ({layer}/{operation}): present {matchedKeysSummary}, missing {missingKeysSummary}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}."
+      "memoryTargetedReadLoaded": "Memory targeted read loaded ({layer}/{operation}): present {matchedKeysSummary}, missing {missingKeysSummary}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}.",
+      "memoryTargetedReadLoadedWithNext": "Memory targeted read loaded ({layer}/{operation}): present {matchedKeysSummary}, missing {missingKeysSummary}, next {nextActionsSummary}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}."
     }
   },
   "manual": {
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
@@ -295,7 +295,8 @@
       "memoryWriteLoaded": "记忆已更新（{layer}/{operation}）：写入 {mutatedCount} 条，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。",
       "memoryEvictLoaded": "记忆清理已完成（{layer}/{operation}）：移除 {evictedCount} 条，命中键 {removedKeysCount} 个，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。",
       "memoryPolicyLoaded": "记忆快照已加载（{layer}/{operation}）：{entriesCount} 条，清理 {evictedCount} 条，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}，推荐动作 {recommendedActionsCount} 个。",
-      "memoryTargetedReadLoaded": "定向记忆读取已加载（{layer}/{operation}）：已命中 {matchedKeysSummary}，缺失 {missingKeysSummary}，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。"
+      "memoryTargetedReadLoaded": "定向记忆读取已加载（{layer}/{operation}）：已命中 {matchedKeysSummary}，缺失 {missingKeysSummary}，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。",
+      "memoryTargetedReadLoadedWithNext": "定向记忆读取已加载（{layer}/{operation}）：已命中 {matchedKeysSummary}，缺失 {missingKeysSummary}，下一步 {nextActionsSummary}，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}。"
     }
   },
   "nodes": "节点",
