feat(agent-workspace): refresh history follow-up ranking

Author: Jacobinwwey

docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md

@@ -466,10 +466,11 @@ It is conversation-product hardening on top of the shipped shell.
 `M8.28` now adds localized result-detail previews inside that recent-activity history so the rail preserves what those actions produced, not just that they happened.
 `M8.29` now adds expandable history drill-down so the rail can reveal event metadata without leaving the active-atom surface.
 `M8.30` now adds deterministic follow-up affordances inside expanded history items so the rail can suggest the next bounded action without leaving that same active-atom surface.
+`M8.31` now makes those follow-up suggestions continuity-aware, so older history entries skip already-completed recent steps when a fresher deterministic action exists.
 
 Priority order:
 
-1. deeper continuity suggestion quality on top of the shipped follow-up-enabled current-atom recent-activity card,
+1. continuity rationale and secondary alternatives on top of the shipped freshness-aware current-atom recent-activity card,
 2. only then deeper personalization work,
 3. markdown-reader improvements only when they clearly compound the same study loop.
 

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,
-- keep closing the correction/product/operator gap exposed after `M8.20-M8.30`,
-- treat `M8.23` as the operator-visibility baseline for conversation-memory/correction actions, `M8.24` as the active-atom action-surface baseline, `M8.25` as the active-atom pane-state continuity baseline, `M8.26` as the active-atom study-loop summary baseline, `M8.27` as the active-atom recent-result continuity baseline, `M8.28` as the active-atom result-preview baseline, `M8.29` as the active-atom history-drill-down baseline, and `M8.30` as the active-atom history follow-up baseline,
-- keep the remaining near-term budget on deeper continuity suggestions instead of reopening backend scope,
+- keep closing the correction/product/operator gap exposed after `M8.20-M8.31`,
+- treat `M8.23` as the operator-visibility baseline for conversation-memory/correction actions, `M8.24` as the active-atom action-surface baseline, `M8.25` as the active-atom pane-state continuity baseline, `M8.26` as the active-atom study-loop summary baseline, `M8.27` as the active-atom recent-result continuity baseline, `M8.28` as the active-atom result-preview baseline, `M8.29` as the active-atom history-drill-down baseline, `M8.30` as the active-atom history follow-up baseline, and `M8.31` as the active-atom history freshness-ranking baseline,
+- keep the remaining near-term budget on continuity rationale and alternative suggestions instead of reopening backend scope,
 - keep remote `main` CI interpretation evidence-based: the latest fully completed `main` workflow set is green, and new pushes should be treated as pending until their workflow set finishes.
 
 ## Current Mainline Snapshot (2026-04-21 M8.18)
@@ -223,21 +223,21 @@ Execution anchor:
   - diagnostics snapshot coverage for stored preview payloads,
   - EN/ZH re-render coverage for localized preview text.
 
-## Latest Mainline Increment (2026-04-21 M8.30 Active-Atom History Follow-Up Affordance)
+## Latest Mainline Increment (2026-04-21 M8.31 Active-Atom History Freshness Ranking)
 
-- Upgraded expanded recent-activity history entries from passive inspection into a bounded next-step surface:
-  - each expanded current-atom history item now resolves one deterministic follow-up action,
-  - follow-up ranking prefers existing point capabilities and only falls back to Focus / Learning Path when no richer capability is available,
-  - clicking the suggested action reuses the same point-action execution path, so the new result flows back into the same bounded recent-history card.
+- Upgraded expanded recent-activity follow-up suggestions from static ranking into continuity-aware ranking:
+  - each expanded current-atom history item now checks whether its preferred follow-up already happened in a more recent history entry,
+  - when a fresher deterministic alternative exists, the rail skips the already-completed step and promotes the next bounded action instead,
+  - when no fresher alternative exists, the rail still falls back to the best valid deterministic follow-up instead of dropping the affordance.
 - Kept the slice frontend-bounded:
   - no backend route, API contract, persistence model, or capability schema changed,
-  - follow-up resolution lives only inside the agent-workspace runtime and reuses the already available point capabilities plus fallback actions.
-- Closed the next continuity gap after `M8.29`:
-  - operators no longer have to inspect history and then manually scan the rail for the most likely next action,
-  - localized rerenders keep both the expanded history metadata and the follow-up affordance pinned through language changes.
+  - freshness ranking lives only inside the agent-workspace runtime and reuses the bounded recent-history list plus the existing point capabilities and fallback actions.
+- Closed the next continuity-quality gap after `M8.30`:
+  - older history items no longer suggest a step that already appears later in the same bounded continuity chain when a fresher deterministic action is available,
+  - the history card now reads more like a real sequence of remaining next steps instead of a static action lookup.
 - Expanded regression coverage for:
-  - recap-history entries surfacing a deterministic `Build Session` follow-up and executing it through the shared runtime action path,
-  - EN/ZH rerender continuity for expanded history follow-up labels and buttons.
+  - older build-session history entries skipping stale `Recap` suggestions in favor of `Follow Up`,
+  - freshness-aware follow-up execution flowing back into the same bounded recent-history card.
 
 ## Latest Mainline Increment (2026-04-14 M1 Baseline)
 
@@ -1342,8 +1342,8 @@ Note: foundation-lane gates now exist on `main`; keep them in the normal verific
 
 1. Treat backend sufficiency as closed-by-default while the gate remains green; do not reopen heavier backend work without new measured pressure.
 2. Treat remote `main` CI as evidence-bound to the latest fully completed workflow set; only reopen CI-triage narrative when a fresh failing run exists.
-3. Make the next planning round about post-`M8.30` bounded conversation-product hardening:
-   - deeper continuity suggestion quality on top of the shipped follow-up-enabled current-atom recent-activity card before deeper personalization work,
+3. Make the next planning round about post-`M8.31` bounded conversation-product hardening:
+   - continuity rationale and secondary alternatives on top of the shipped freshness-aware current-atom recent-activity card before deeper personalization work,
    - only then deeper personalization work,
    - markdown-reader improvements only when they compound the same study loop.
 4. Treat notification-threshold governance as closed after `M7.29`; do not plan `M7.30+` unless a materially new operator requirement appears.

docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md

@@ -247,8 +247,8 @@ Recommended next product order:
    - extend explicit conversation memory APIs beyond the current snapshot/read/managed-key inspection and note/correction/eviction surface,
    - the minimum correction / feedback closure is now integrated through explicit next-step guidance on missing managed state,
    - operator-facing visibility for conversation-memory and correction actions is now integrated through persisted diagnostics summary/index counts,
-   - stronger agent action surfaces around focus mode and learning path are now integrated through the active-atom quick-action rail, toolbar routing, continuity notes/path-target diagnostics, capability-taxonomy summary cards, the recent-activity history card, localized result-detail previews on that history surface, expandable history drill-down, and deterministic history follow-up affordances,
-   - next prioritize deeper continuity suggestion quality on top of the shipped follow-up-enabled current-atom recent-activity card before deeper personalization work.
+   - stronger agent action surfaces around focus mode and learning path are now integrated through the active-atom quick-action rail, toolbar routing, continuity notes/path-target diagnostics, capability-taxonomy summary cards, the recent-activity history card, localized result-detail previews on that history surface, expandable history drill-down, deterministic history follow-up affordances, and continuity-aware freshness ranking for those affordances,
+   - next prioritize continuity rationale and secondary alternatives on top of the shipped freshness-aware current-atom recent-activity card before deeper personalization work.
 2. markdown-reader improvement:
    - only when it clearly compounds knowledge review or focus-mode study loops.
 

docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md

@@ -454,10 +454,11 @@
 `M8.28` 现在又在这条 recent-activity history 里补上本地化 result-detail preview，让 rail 保留的不只是“发生过什么动作”，还包括“动作产出了什么”。
 `M8.29` 现在又补上可展开的 history drill-down，让 rail 不离开当前 atom surface 也能检查事件元数据。
 `M8.30` 现在又在展开的 history item 内补上确定性的 follow-up affordance，让 rail 在同一块 active-atom surface 内就能建议下一个有界动作。
+`M8.31` 现在又让这条 follow-up suggestion 具备 continuity-aware freshness：只要存在更新鲜的确定性动作，较旧 history item 就会跳过已经完成过的近期步骤。
 
 优先顺序：
 
-1. 围绕已落地且已带 follow-up affordance 的 current-atom recent-activity card 继续补更深的 continuity suggestion quality，
+1. 围绕已落地且已带 freshness-aware follow-up 的 current-atom recent-activity card 继续补 continuity rationale 与 secondary alternative，
 2. 之后才进入更深的 personalization 工作，
 3. Markdown 阅读器提升只有在能明确复利同一学习闭环时才进入前列。
 

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

@@ -18,9 +18,9 @@
 当前重心是 **建立在已转绿 backend 基线之上的 conversation-product 加固**：
 
 - 让 backend sufficiency 继续作为常驻 decision gate，而不是继续占用主动执行预算，
-- 持续收口 `M8.20-M8.30` 之后暴露出的 correction / product / operator 缺口，
-- 将 `M8.23` 视作 conversation-memory / correction action 的 operator-visibility 基线，将 `M8.24` 视作当前 atom action-surface 基线，将 `M8.25` 视作当前 atom pane-state continuity 基线，将 `M8.26` 视作当前 atom study-loop summary 基线，将 `M8.27` 视作当前 atom recent-result continuity 基线，将 `M8.28` 视作当前 atom result-preview 基线，将 `M8.29` 视作当前 atom history-drill-down 基线，并将 `M8.30` 视作当前 atom history follow-up 基线，
-- 把剩余近端预算继续压在更深的 continuity suggestion 上，而不是重开 backend 范围，
+- 持续收口 `M8.20-M8.31` 之后暴露出的 correction / product / operator 缺口，
+- 将 `M8.23` 视作 conversation-memory / correction action 的 operator-visibility 基线，将 `M8.24` 视作当前 atom action-surface 基线，将 `M8.25` 视作当前 atom pane-state continuity 基线，将 `M8.26` 视作当前 atom study-loop summary 基线，将 `M8.27` 视作当前 atom recent-result continuity 基线，将 `M8.28` 视作当前 atom result-preview 基线，将 `M8.29` 视作当前 atom history-drill-down 基线，将 `M8.30` 视作当前 atom history follow-up 基线，并将 `M8.31` 视作当前 atom history freshness-ranking 基线，
+- 把剩余近端预算继续压在 continuity rationale 与 alternative suggestion 上，而不是重开 backend 范围，
 - 远端 `main` CI 解释继续基于代码事实：最近一组已完整结束的主线工作流为绿色，新推送在整组工作流结束前只应视为 pending。
 
 ## 当前主线快照（2026-04-21 M8.18）
@@ -223,21 +223,21 @@
   - diagnostics snapshot 中 preview payload 的可见性，
   - EN/ZH 对 preview 文本的重渲覆盖。
 
-## 主线最新增量（2026-04-21 M8.30 当前 Atom History Follow-Up Affordance）
+## 主线最新增量（2026-04-21 M8.31 当前 Atom History Freshness Ranking）
 
-- 已把展开后的 recent-activity history item 从“只可检查”继续升级为“带下一步建议”的 bounded surface：
-  - 每条展开中的当前 atom history item 现在都会解析出一个确定性的 follow-up action，
-  - follow-up 排序优先复用当前 point 已有 capability，只有没有更合适动作时才退回到 Focus / Learning Path，
-  - 点击建议动作会继续复用同一条 point-action 执行链路，因此新结果会直接回流到同一张 recent-history card。
+- 已把展开后的 recent-activity follow-up suggestion 从静态排序继续升级为 continuity-aware ranking：
+  - 每条展开中的当前 atom history item 现在都会检查它的首选 follow-up 是否已经在更近的一条 history entry 中发生过，
+  - 如果存在更新鲜的确定性替代动作，rail 会跳过这个已经完成的步骤，改为推荐下一个有界动作，
+  - 如果没有更新鲜的替代动作，rail 仍会回退到最合适的确定性 follow-up，而不是直接丢掉这条 affordance。
 - 范围继续保持在前端层：
   - 没有新增 backend route、API contract、持久化模型或 capability schema，
-  - follow-up 解析完全驻留在 agent-workspace runtime 内，只复用已有 point capabilities 与 fallback actions。
-- 已收口 `M8.29` 之后的下一个 continuity 缺口：
-  - 用户不再需要先展开 history，再手动扫描整条 rail 去判断下一个最可能动作，
-  - 语言切换时，展开中的 history metadata 与 follow-up affordance 都会保持稳定，不会丢失当前上下文。
+  - freshness ranking 完全驻留在 agent-workspace runtime 内，只复用有界 recent-history 列表、已有 point capabilities 与 fallback actions。
+- 已收口 `M8.30` 之后的下一个 continuity-quality 缺口：
+  - 对于更旧的 history item，只要存在更新鲜的确定性动作，界面就不会再推荐那种已经在后续 history 里出现过的步骤，
+  - history card 更接近“剩余下一步序列”，而不再只是静态动作映射表。
 - 回归覆盖同步扩展到：
-  - recap history item 暴露确定性的 `Build Session` follow-up，并通过共享 runtime action path 执行，
-  - EN/ZH 对 history follow-up 标签与按钮的重渲 continuity。
+  - 更旧的 build-session history item 会跳过陈旧的 `Recap` 建议，改推 `Follow Up`，
+  - freshness-aware follow-up 执行后，会继续回流到同一张 bounded recent-history card。
 
 ## 主线最新增量（2026-04-14 M1 基线）
 
@@ -1345,8 +1345,8 @@ npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBa
 
 1. backend sufficiency 在 gate 继续为绿时默认视为已收口；没有新的 measured pressure 前，不重开更重 backend 工作。
 2. 远端 `main` CI 继续以最近一组已完整结束的工作流为事实依据；只有出现新的失败 run，才重开 CI-triage 叙事。
-3. 下一轮 planning 应只讨论 post-`M8.30` 的有界 conversation-product 加固：
-   - 围绕已落地且已带 follow-up affordance 的 current-atom recent-activity card 继续补更深的 continuity suggestion quality，再进入更深 personalization，
+3. 下一轮 planning 应只讨论 post-`M8.31` 的有界 conversation-product 加固：
+   - 围绕已落地且已带 freshness-aware follow-up 的 current-atom recent-activity card 继续补 continuity rationale 与 secondary alternative，再进入更深 personalization，
    - 之后才进入更深的 personalization 工作，
    - Markdown 阅读器提升只有在能复利同一学习闭环时才进入前列。
 4. notification-threshold 治理链路继续视为在 `M7.29` 后已收口；没有新的强运维需求前，不再规划 `M7.30+`。

docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md

@@ -246,8 +246,8 @@
    - 在当前 snapshot/read/托管 key 检查与 note/correction/eviction 能力之上继续扩展显式 conversation memory API，
    - 最小 correction / feedback 收口已经通过“缺失托管状态 -> 显式下一步提示”集成到主线，
    - conversation-memory / correction action 的 operator-facing visibility 已经通过持久化 diagnostics summary / index 计数集成到主线，
-   - 围绕 focus mode 与 learning path 的更强 agent action surface 已经通过当前 atom quick-action rail、toolbar routing、continuity note / path-target diagnostics、capability-taxonomy summary card、recent-activity history card、这张卡上的本地化 result-detail preview、可展开的 history drill-down，以及确定性的 history follow-up affordance 集成到主线，
-   - 下一步是在更深 personalization 之前，优先围绕已落地且已带 follow-up affordance 的 current-atom recent-activity card 继续补更深的 continuity suggestion quality。
+   - 围绕 focus mode 与 learning path 的更强 agent action surface 已经通过当前 atom quick-action rail、toolbar routing、continuity note / path-target diagnostics、capability-taxonomy summary card、recent-activity history card、这张卡上的本地化 result-detail preview、可展开的 history drill-down、确定性的 history follow-up affordance，以及这条 affordance 的 continuity-aware freshness ranking 集成到主线，
+   - 下一步是在更深 personalization 之前，优先围绕已落地且已带 freshness-aware follow-up 的 current-atom recent-activity card 继续补 continuity rationale 与 secondary alternative。
 2. markdown reader 提升：
    - 只有在它能明确加强知识 review 或 focus-mode 学习闭环时，再提升优先级。