feat(agent-workspace): explain history follow-up choices

Author: Jacobinwwey

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

@@ -467,10 +467,11 @@ It is conversation-product hardening on top of the shipped shell.
 `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.
+`M8.32` now explains those freshness-aware suggestions and exposes one secondary alternative, so expanded history items read like bounded decision surfaces instead of opaque action picks.
 
 Priority order:
 
-1. continuity rationale and secondary alternatives on top of the shipped freshness-aware current-atom recent-activity card,
+1. deeper continuity explanation quality and confidence signals on top of the shipped rationale-enabled 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.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 closing the correction/product/operator gap exposed after `M8.20-M8.32`,
+- 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, `M8.31` as the active-atom history freshness-ranking baseline, and `M8.32` as the active-atom history rationale/alternative baseline,
+- keep the remaining near-term budget on deeper continuity explanation quality 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.31 Active-Atom History Freshness Ranking)
+## Latest Mainline Increment (2026-04-21 M8.32 Active-Atom History Rationale And Alternatives)
 
-- 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.
+- Upgraded freshness-aware history follow-up suggestions into a more legible continuity surface:
+  - each expanded current-atom history item now explains why the suggested next step was chosen,
+  - the rail now exposes one secondary alternative alongside the primary follow-up when another bounded action is still valid,
+  - rationale text distinguishes between top-ranked suggestions and stale-step skips caused by more recent history.
 - Kept the slice frontend-bounded:
   - no backend route, API contract, persistence model, or capability schema changed,
-  - 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.
+  - rationale and alternative resolution live only inside the agent-workspace runtime and reuse the bounded recent-history list plus the existing point capabilities and fallback actions.
+- Closed the next continuity-explanation gap after `M8.31`:
+  - operators no longer have to infer why a primary suggestion changed after freshness ranking,
+  - the history card now exposes a primary next step and one nearby alternative without forcing the operator back to the wider rail.
 - Expanded regression coverage for:
-  - 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.
+  - stale-step skips now rendering explicit rationale copy plus a bounded secondary alternative,
+  - EN/ZH rerenders keeping rationale text and secondary-alternative labels stable inside expanded history details.
 
 ## 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.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,
+3. Make the next planning round about post-`M8.32` bounded conversation-product hardening:
+   - deeper continuity explanation quality and confidence signals on top of the shipped rationale-enabled 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, 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.
+   - 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, continuity-aware freshness ranking for those affordances, and bounded rationale/secondary-alternative rendering,
+   - next prioritize deeper continuity explanation quality and confidence signals on top of the shipped rationale-enabled 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

@@ -455,10 +455,11 @@
 `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 就会跳过已经完成过的近期步骤。
+`M8.32` 现在又给这条 freshness-aware suggestion 补上原因解释与一个 secondary alternative，让展开后的 history item 更像有界决策面，而不是黑盒动作推荐。
 
 优先顺序：
 
-1. 围绕已落地且已带 freshness-aware follow-up 的 current-atom recent-activity card 继续补 continuity rationale 与 secondary alternative，
+1. 围绕已落地且已带 rationale 的 current-atom recent-activity card 继续补更深的 continuity explanation quality 与 confidence signal，
 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.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 范围，
+- 持续收口 `M8.20-M8.32` 之后暴露出的 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 基线，并将 `M8.32` 视作当前 atom history rationale/alternative 基线，
+- 把剩余近端预算继续压在更深的 continuity explanation quality 上，而不是重开 backend 范围，
 - 远端 `main` CI 解释继续基于代码事实：最近一组已完整结束的主线工作流为绿色，新推送在整组工作流结束前只应视为 pending。
 
 ## 当前主线快照（2026-04-21 M8.18）
@@ -223,21 +223,21 @@
   - diagnostics snapshot 中 preview payload 的可见性，
   - EN/ZH 对 preview 文本的重渲覆盖。
 
-## 主线最新增量（2026-04-21 M8.31 当前 Atom History Freshness Ranking）
+## 主线最新增量（2026-04-21 M8.32 当前 Atom History Rationale And Alternatives）
 
-- 已把展开后的 recent-activity follow-up suggestion 从静态排序继续升级为 continuity-aware ranking：
-  - 每条展开中的当前 atom history item 现在都会检查它的首选 follow-up 是否已经在更近的一条 history entry 中发生过，
-  - 如果存在更新鲜的确定性替代动作，rail 会跳过这个已经完成的步骤，改为推荐下一个有界动作，
-  - 如果没有更新鲜的替代动作，rail 仍会回退到最合适的确定性 follow-up，而不是直接丢掉这条 affordance。
+- 已把 freshness-aware history follow-up suggestion 继续升级为更可读的 continuity surface：
+  - 每条展开中的当前 atom history item 现在都会解释为什么当前这一步会成为主建议动作，
+  - 只要还有另一个有界动作仍然有效，rail 现在就会在主建议旁再暴露一个 secondary alternative，
+  - rationale 文本会区分“正常最高优先级建议”与“因较新 history 已覆盖旧步骤而发生的跳步”。
 - 范围继续保持在前端层：
   - 没有新增 backend route、API contract、持久化模型或 capability schema，
-  - freshness ranking 完全驻留在 agent-workspace runtime 内，只复用有界 recent-history 列表、已有 point capabilities 与 fallback actions。
-- 已收口 `M8.30` 之后的下一个 continuity-quality 缺口：
-  - 对于更旧的 history item，只要存在更新鲜的确定性动作，界面就不会再推荐那种已经在后续 history 里出现过的步骤，
-  - history card 更接近“剩余下一步序列”，而不再只是静态动作映射表。
+  - rationale 与 alternative 解析完全驻留在 agent-workspace runtime 内，只复用有界 recent-history 列表、已有 point capabilities 与 fallback actions。
+- 已收口 `M8.31` 之后的下一个 continuity-explanation 缺口：
+  - 用户不再需要自己猜测 freshness ranking 为什么会把主建议从某个旧步骤切换到新步骤，
+  - history card 现在能在同一块展开区域里同时暴露主建议与一个邻近 alternative，而不用回到更宽的 rail 再手动筛选。
 - 回归覆盖同步扩展到：
-  - 更旧的 build-session history item 会跳过陈旧的 `Recap` 建议，改推 `Follow Up`，
-  - freshness-aware follow-up 执行后，会继续回流到同一张 bounded recent-history card。
+  - stale-step skip 现在会显示明确的 rationale 文本与一个有界 secondary alternative，
+  - EN/ZH 重渲时，rationale 文本与 secondary-alternative 标签会在展开中的 history detail 内保持稳定。
 
 ## 主线最新增量（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.31` 的有界 conversation-product 加固：
-   - 围绕已落地且已带 freshness-aware follow-up 的 current-atom recent-activity card 继续补 continuity rationale 与 secondary alternative，再进入更深 personalization，
+3. 下一轮 planning 应只讨论 post-`M8.32` 的有界 conversation-product 加固：
+   - 围绕已落地且已带 rationale 的 current-atom recent-activity card 继续补更深的 continuity explanation quality 与 confidence signal，再进入更深 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，以及这条 affordance 的 continuity-aware freshness ranking 集成到主线，
-   - 下一步是在更深 personalization 之前，优先围绕已落地且已带 freshness-aware follow-up 的 current-atom recent-activity card 继续补 continuity rationale 与 secondary alternative。
+   - 围绕 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，以及有界的 rationale / secondary-alternative 渲染集成到主线，
+   - 下一步是在更深 personalization 之前，优先围绕已落地且已带 rationale 的 current-atom recent-activity card 继续补更深的 continuity explanation quality 与 confidence signal。
 2. markdown reader 提升：
    - 只有在它能明确加强知识 review 或 focus-mode 学习闭环时，再提升优先级。