dsh-workplan 1.5.1 → 1.5.2

package/src/client.ts

@@ -45,6 +45,9 @@ window.__ModuleLoader__.load({
         "helpNobody": "还没开始",
         "helpDone": "都做完了",
         "helpNextDone": "没有下一步，这件事已完成",
+        "helpWaitActive": "等这一步做完，再继续下一项",
+        "helpNoPlan": "还没有安排任何工作",
+        "nowRemaining": "还剩 {n} 项",
         "helpHint": "负责团队 = 谁来做；具体工作 = 要完成的一件事；卡住了 = 需要人处理。",
         "handleBlocked": "先处理",
         "resumeReady": "对主 Agent 说「续跑这个计划」，会从受阻处继续（已完成的不重跑）",
@@ -207,6 +210,9 @@ window.__ModuleLoader__.load({
         "helpNobody": "Not started yet",
         "helpDone": "Everything is done",
         "helpNextDone": "Nothing next; this task is complete",
+        "helpWaitActive": "Wait for this step to finish, then continue",
+        "helpNoPlan": "No work has been scheduled yet",
+        "nowRemaining": "{n} item(s) left",
         "helpHint": "Team = who does it; work item = one thing to finish; stuck = a person needs to help.",
         "handleBlocked": "Fix first",
         "resumeReady": "Tell the main agent to resume this plan; it continues from the blocked step without re-running finished work",
@@ -1028,14 +1034,21 @@ window.__ModuleLoader__.load({
     }
 
     function workerText(session: any, t: any) {
-      const active = findEntry(session, 'in_progress')
-      if (active) {
-        return `${deptName(t, active.subtask.department)} · ${active.subtask.title}`
-      }
+      /*
+       * [1.5.2] 与 `planNow` 同序：卡住优先。
+       *
+       * 旧顺序是「正在做」优先，而卡片右上角的「现在」是「卡住了」优先，
+       * 于是同一屏一边说「现在卡住了 T1」、一边说「正在做 T2」（T5 C12）。
+       * 卡住需要人介入，两个位置都应先报它。
+       */
       const blocked = findEntry(session, 'blocked')
       if (blocked) {
         return `${deptName(t, blocked.subtask.department)} · ${blocked.subtask.title}（${t('status.blocked')}）`
       }
+      const active = findEntry(session, 'in_progress')
+      if (active) {
+        return `${deptName(t, active.subtask.department)} · ${active.subtask.title}`
+      }
       const stats = session.stats || {}
       if ((stats.total ?? 0) > 0 && (stats.done ?? 0) >= (stats.total ?? 0)) return t('helpDone')
       return t('helpNobody')
@@ -1061,11 +1074,22 @@ window.__ModuleLoader__.load({
     function nextText(session: any, t: any) {
       const blocked = findEntry(session, 'blocked')
       if (blocked) return `${t('handleBlocked')}：${deptName(t, blocked.subtask.department)} · ${blocked.subtask.title}${resumeHint(session, t)}`
+      /*
+       * [1.5.2] 「没有下一步」只允许出现在真正全部完成之后。
+       *
+       * 旧实现找不到 pending 就直接 return「没有下一步，这件事已完成」，于是
+       *   · 单任务计划刚进入 in_progress（环 0%）→ 同一张卡宣布「已完成」（T5 C2）；
+       *   · 降级计划 0/0 → 一边「安排失败」一边「已完成」（T5 C11）。
+       * 现在先按计数判终态，再区分「等当前这一步」「根本没有计划」。
+       */
+      const counts = planCounts(session.stats || {})
+      if (counts.total > 0 && counts.done === counts.total) return t('helpDone')
+      if (counts.total === 0) return t('helpNoPlan')
       const next = findEntry(session, 'pending') || allEntries(session).find((entry: any) => !entry.item)
       if (next) return `${deptName(t, next.subtask.department)} · ${next.subtask.title}`
-      const stats = session.stats || {}
-      if ((stats.total ?? 0) > 0 && (stats.done ?? 0) >= (stats.total ?? 0)) return t('helpDone')
-      return t('helpNextDone')
+      const active = findEntry(session, 'in_progress')
+      if (active) return `${t('helpWaitActive')}：${deptName(t, active.subtask.department)} · ${active.subtask.title}`
+      return t('helpWaitActive')
     }
 
     function progressText(item: any, t: any) {
@@ -1339,15 +1363,19 @@ window.__ModuleLoader__.load({
       const done = items.filter(({ item }: any) => item?.status === 'done').length
       const blocked = items.filter(({ item }: any) => item?.status === 'blocked').length
       const inProgress = items.some(({ item }: any) => item?.status === 'in_progress')
-      const tone = blocked > 0 ? 'blocked' : done === items.length ? 'done' : inProgress ? 'active' : 'idle'
+      // [1.5.2] 与 `planStageRows` 同一条规则：有 done 就是 active，不再只在
+      // 有 in_progress 时才算「正在做」。旧规则让同一阶段在概览行显示「正在做」、
+      // 在阶段卡显示「还没开始」（T5 C9）。
+      const tone = blocked > 0 ? 'blocked' : items.length > 0 && done === items.length ? 'done' : inProgress || done > 0 ? 'active' : 'idle'
       // Same tone/counts as before; only the presentation moved into the
       // collapsed summary row (done/total + state pill), so the numbers keep one
       // source: this step's own items from `statuses`.
       const stateText = blocked > 0
         ? `${blocked} ${t('stats.blocked')}`
-        : done === items.length
+        : items.length > 0 && done === items.length
           ? t('helpDone')
-          : inProgress ? t('phase.executing') : t('phase.pending')
+          : inProgress ? t('phase.executing')
+            : done > 0 ? fill(t('nowRemaining'), { n: items.length - done }) : t('phase.pending')
       return h('section', { className: `dsh-wp-stage dsh-wp-tone-${tone}` },
         h(Collapse, {
           className: 'dsh-wp-stage-collapse',
@@ -1463,6 +1491,18 @@ window.__ModuleLoader__.load({
       return Math.max(0, Math.round(number))
     }
 
+    /*
+     * [1.5.2] 计划级百分比的唯一算式。
+     *
+     * 1.5.1 及以前，同一页面上至少有三处各自 `Math.round(done / total * 100)`：
+     * 卡片环（planCounts）、组头环（groupTotals）、按任务进度条（TaskBars / 总览柱状图）。
+     * 三份实现口径相同只是巧合，任何一处单独改动都会让「同一张卡两个百分比」重现。
+     * 现在只有这一个函数，其它地方一律调用它。
+     */
+    function planPercent(done: number, total: number): number | null {
+      return total > 0 ? Math.round((done / total) * 100) : null
+    }
+
     // 与 groupTotals 同一套口径：先夹到 [0,total]，再让「正在做/还没开始」
     // 吃掉剩余量，四段之和恒等于总数（构成条不会溢出或出现负宽度）。
     function planCounts(stats: any): PlanCounts {
@@ -1472,8 +1512,44 @@ window.__ModuleLoader__.load({
       const blocked = Math.min(planCount(source.blocked), total - done)
       const active = Math.min(planCount(source.inProgress), total - done - blocked)
       const pending = Math.max(0, total - done - blocked - active)
-      const percent = total > 0 ? Math.round((done / total) * 100) : null
-      return { total, done, active, blocked, pending, percent }
+      return { total, done, active, blocked, pending, percent: planPercent(done, total) }
+    }
+
+    /*
+     * [1.5.2] 完成语义的第二道保险：状态文案必须服从计数事实。
+     *
+     * 后端已保证「工作项全部 done ⇒ phase=done」（`reconcilePhase`）。这里再兜一层，
+     * 让任何历史载荷、旧缓存或第三方构造的 payload 都不可能渲染出「100% + 正在
+     * 收尾」：计数齐全且全部完成时一律按「已完成」呈现；反过来，phase 说 done
+     * 但计数里还有没做完的项时，按真实计数降级，避免「已完成下面挂着没做完的活」。
+     *
+     * 计数未知（total=0，例如已取消或尚未拆解）时不动原始 phase——此时没有事实
+     * 可以覆盖它，硬改会把「进行中/已完成」的分组依据一起抹掉。
+     * 「integrating」只在计数证明全部完成时升级为 done，否则保留原语义（回放旧会话）。
+     */
+    function planPhaseOf(rawPhase: any, counts: PlanCounts): string {
+      const phase = String(rawPhase ?? 'pending')
+      if (counts.total > 0) {
+        if (counts.done === counts.total) return 'done'
+        if (phase === 'done') {
+          if (counts.blocked > 0) return 'blocked'
+          if (counts.active > 0) return 'executing'
+          return 'pending'
+        }
+      }
+      return phase
+    }
+
+    /*
+     * [1.5.2] 加权总进度的展示口径：未全部完成时封顶 99。
+     *
+     * 服务端 `deriveAggregates` 已做同样封顶；这里再算一次是为了让旧载荷/手工
+     * fixture 也守同一条不变量——「总体进度 100%」绝不能与「还有 N 项没完成」同屏。
+     */
+    function planWeightedPercent(stats: any, counts: PlanCounts): number {
+      const weighted = clampPct(stats?.progress ?? 0)
+      if (counts.total > 0 && counts.done === counts.total) return 100
+      return Math.min(99, weighted)
     }
 
     function planStatusMap(statuses: any): Map<string, any> {
@@ -1555,6 +1631,16 @@ window.__ModuleLoader__.load({
         return { state: 'active', text: withTitle(t('stats.inProgress'), active?.title) }
       }
       if (counts.total > 0 && counts.done === counts.total) return { state: 'done', text: t('helpDone') }
+      /*
+       * [1.5.2] 部分完成不再落到「还没开始」。
+       *
+       * `done>0` 但没有 blocked、也没有 in_progress 时（预算把剩余项重置成
+       * pending，或剩余项还没轮到），旧代码直接返回 `stats.pending`「还没开始」，
+       * 与同一张卡上的「1/2 做好了」和 50% 直接冲突（T5 C5）。
+       */
+      if (counts.done > 0) {
+        return { state: 'active', text: fill(t('nowRemaining'), { n: counts.total - counts.done }) }
+      }
       return { state: 'pending', text: t('stats.pending') }
     }
 
@@ -1643,7 +1729,9 @@ window.__ModuleLoader__.load({
       if (rows.length < 1 || rows.length > 12) return null
       return h('div', { className: 'dsh-wp-stepper', 'aria-hidden': 'true', 'data-stages': String(rows.length) },
         rows.map((row) => {
-          const reach = row.total > 0 ? ((row.done + row.active + row.blocked) / row.total) * 100 : 0
+          // [1.5.2] 只按 done 计。旧式把 blocked/active 也算「触达」，于是环 50%
+          // 时阶段条已经全满（T5 C7）——同一张卡两个「完成度」。
+          const reach = row.total > 0 ? (row.done / row.total) * 100 : 0
           const width = row.tone === 'pending' ? 0 : reach
           return h('span', {
             key: row.id,
@@ -1664,11 +1752,20 @@ window.__ModuleLoader__.load({
     }
 
     function PlanViz({ t, counts, now, rows }: { t: (key: string) => string; counts: PlanCounts; now: PlanNow; rows: PlanStageRow[] }) {
+      /*
+       * [1.5.2] data-state 也是「完成语义」的一个读者。
+       *
+       * 旧实现只看 percent：0% 的 pending 卡拿到 data-state="active"，
+       * 而 100% 的卡即使 phase 说 integrating 也是 "done"（T5 C13/C1）。
+       * 现在与胶囊、分组、环共用计数：全 done 才 done，0 且有未完成才 idle。
+       */
       const state = counts.percent === null
         ? 'idle'
         : counts.blocked > 0
           ? 'blocked'
-          : counts.percent >= 100 ? 'done' : 'active'
+          : counts.total > 0 && counts.done === counts.total
+            ? 'done'
+            : counts.done > 0 || counts.active > 0 ? 'active' : 'idle'
       return h('div', {
         className: 'dsh-wp-planviz',
         'data-percent': counts.percent === null ? 'none' : String(counts.percent),
@@ -1708,7 +1805,7 @@ window.__ModuleLoader__.load({
           h('span', null, `${counts.done}/${counts.total} ${t('stats.done')}`),
         ),
         h('div', { className: 'dsh-wp-planoverview-stats' },
-          h('span', null, `${t('vizWeighted')} ${clampPct(stats?.progress ?? 0)}%`),
+          h('span', null, `${t('vizWeighted')} ${planWeightedPercent(stats, counts)}%`),
           h('span', null, `${counts.active} ${t('stats.inProgress')} · ${counts.pending} ${t('stats.pending')}`),
           counts.blocked > 0 ? h('span', null, `${counts.blocked} ${t('stats.blocked')}`) : null,
         ),
@@ -1742,13 +1839,18 @@ window.__ModuleLoader__.load({
 
     function SessionCard({ session, t, open, onToggle }: any) {
       const domId = `dsh-wp-session-${session.sessionId}`
-      const phase = session.phase || 'pending'
       const stats = session.stats || {}
-      const tone = phaseTone(phase)
-      const departments = Array.isArray(session.departments) ? session.departments : []
       // 1.5.0：折叠卡摘要＝图表（环 + 百分比 + 四段构成条 + 图例 + 阶段步进条）；
       // 数字仍只来自 session.stats，与旧头部的口径完全一致，不引入第二套统计。
       const counts = planCounts(stats)
+      /*
+       * [1.5.2] 卡片的色调与胶囊文案也走统一对账：只要计数显示全部完成，
+       * 胶囊就必须是「已完成」，视觉档位也必须是 done。截图里那张卡之所以
+       * 「100% + 正在收尾 + 留在进行中组」，就是因为这三个读者各读各的字段。
+       */
+      const phase = planPhaseOf(session.phase || 'pending', counts)
+      const tone = phaseTone(phase)
+      const departments = Array.isArray(session.departments) ? session.departments : []
       const statuses = Array.isArray(session.statuses) ? session.statuses : []
       const stageRows = planStageRows(session.stages, statuses)
       const now = planNow(t, counts, planTaskEntries(session.stages, statuses))
@@ -1989,7 +2091,7 @@ window.__ModuleLoader__.load({
         total,
         done,
         open: total - done,
-        percent: total > 0 ? Math.round((done / total) * 100) : null,
+        percent: planPercent(done, total),
         active: Math.max(0, active),
         pending: Math.max(0, pending),
         blocked: Math.max(0, blocked),
@@ -2209,10 +2311,11 @@ window.__ModuleLoader__.load({
         h('div', { className: 'dsh-wp-section-title' }, t('taskChart')),
         (Array.isArray(sessions) ? sessions : []).map((session: any) => {
           const stats = session.stats || {}
-          const total = Math.max(0, Number(stats.total) || 0)
-          const done = Math.max(0, Number(stats.done) || 0)
-          const percent = total > 0 ? Math.round((done / total) * 100) : 0
-          const tone = phaseTone(session.phase || 'pending')
+          const counts = planCounts(stats)
+          // 同一套计数与对账：柱状图的百分比、文案、色调都不得自成一套。
+          const percent = counts.percent ?? 0
+          const phase = planPhaseOf(session.phase || 'pending', counts)
+          const tone = phaseTone(phase)
           return h('button', {
             key: session.sessionId,
             type: 'button',
@@ -2222,13 +2325,13 @@ window.__ModuleLoader__.load({
           },
             h('div', { className: 'dsh-wp-bar-head' },
               h('span', { className: 'dsh-wp-bar-title' }, session.title || t('panel')),
-              h('span', { className: 'dsh-wp-bar-value' }, `${done}/${total}`),
+              h('span', { className: 'dsh-wp-bar-value' }, `${counts.done}/${counts.total}`),
             ),
             h('div', { className: 'dsh-wp-bar-track' },
               h('div', { className: `dsh-wp-bar-fill dsh-wp-bar-fill--${tone}`, style: { width: `${percent}%` } }),
             ),
             h('div', { className: 'dsh-wp-bar-meta' },
-              h('span', null, t(`phase.${session.phase || 'pending'}`)),
+              h('span', null, t(`phase.${phase}`)),
               h('span', null, `${percent}%`),
             ),
           )
@@ -2282,8 +2385,16 @@ window.__ModuleLoader__.load({
         const live: any[] = []
         const finished: any[] = []
         const urgentPhases = ['blocked', 'degraded', 'paused']
+        /*
+         * [1.5.2] 分组也按对账后的 phase，而不是 payload 里的原始 phase。
+         *
+         * 截图那张卡之所以停在「进行中」组，就是因为这里只读 `session.phase`：
+         * 14/14、100% 的计划带着 integrating 被塞进 live 组，组头于是出现
+         * 「未完成 0 / 已完成 14（完成率 100%）」却仍标着「进行中」。
+         * `planPhaseOf` 让分组、组头计数、卡片胶囊共用同一个结论。
+         */
         for (const session of activeSessions) {
-          if (session.phase === 'done') finished.push(session)
+          if (planPhaseOf(session.phase, planCounts(session.stats)) === 'done') finished.push(session)
           else live.push(session)
         }
         /*
@@ -2301,7 +2412,7 @@ window.__ModuleLoader__.load({
           planning: 4,
           pending: 5,
         }
-        const rank = (session: any) => phaseRank[session.phase] ?? 5
+        const rank = (session: any) => phaseRank[planPhaseOf(session.phase, planCounts(session.stats))] ?? 5
         live.sort((a: any, b: any) => (rank(a) - rank(b))
           || ((Number(b.createdAt) || 0) - (Number(a.createdAt) || 0))
           || String(a.sessionId).localeCompare(String(b.sessionId)))
@@ -2330,12 +2441,11 @@ window.__ModuleLoader__.load({
         return { live, finished, urgent: live.filter((session: any) => urgentPhases.includes(session.phase)).length }
       }, [activeSessions])
       const liveBars = useMemo(() => groups.live.slice(0, 6).map((session: any) => {
-        const doneCount = session.stats?.done ?? 0
-        const totalCount = session.stats?.total ?? 0
         const raw = String(session.title || t('panel'))
         return {
           label: raw.length > 14 ? `${raw.slice(0, 14)}…` : raw,
-          value: totalCount > 0 ? Math.round((doneCount / totalCount) * 100) : 0,
+          // [1.5.2] 与卡片/组头同一个百分比函数，杜绝第二套口径。
+          value: planPercent(planCount(session.stats?.done), planCount(session.stats?.total)) ?? 0,
         }
       }), [groups, t])
       return h('div', { className: 'dsh-wp' },
@@ -2389,12 +2499,19 @@ window.__ModuleLoader__.load({
         const active = ['planning', 'executing', 'blocked'].includes(session.phase)
         if (currentTurn > createdTurn && !active) return null
       }
+      /*
+       * [1.5.2] 会话内联卡（TurnCard）也走同一套对账。
+       *
+       * 面板卡片修好了、内联卡却仍按原始 phase 渲染的话，同一张计划会在
+       * 「侧栏已完成 / 对话里正在收尾」之间再次自相矛盾。
+       */
       const stats = session.stats || {}
-      const tone = phaseTone(session.phase || 'pending')
+      const phase = planPhaseOf(session.phase || 'pending', planCounts(stats))
+      const tone = phaseTone(phase)
       return h('div', { className: `dsh-wp-turn dsh-wp-tone-${tone}` },
         h('div', { className: 'dsh-wp-turn-title' },
           h('span', null, session.title || t('panel')),
-          h(Pill, { tone }, t(`phase.${session.phase || 'pending'}`)),
+          h(Pill, { tone }, t(`phase.${phase}`)),
         ),
         h('div', { className: 'dsh-wp-muted', style: { marginTop: '6px' } },
           `${t('helpWho')}：${workerText(session, t)}`),

package/src/host.ts

@@ -325,7 +325,7 @@ export function apply(ctx: any, config: WorkplanConfig = {}) {
 
 export const meta = {
   name,
-  version: '1.5.1',
+  version: '1.5.2',
   promptOrder: PROMPT_ORDER,
   routes: ['/dsh-workplan/plans', '/dsh-workplan/vendor/chart.umd.js'],
 }

package/src/plan.ts

@@ -1074,8 +1074,16 @@ export function applyStatus(statuses: any, subtaskId: any, patch: any) {
     if (patch.summary === undefined) next.summary = ''
     if (patch.error === undefined) next.error = null
   }
-  if (patch.status === 'in_progress' && next.startedAt === null) {
-    next.startedAt = Date.now()
+  if (patch.status === 'in_progress') {
+    if (next.startedAt === null) next.startedAt = Date.now()
+    /*
+     * [1.5.2] 「正在做」不允许自称 100%。
+     *
+     * 工具允许 `{status:'in_progress', progress:100}`，界面于是出现
+     * 「正在做 + 进度 100%」，计划层再叠一个环 0% / 加权 100%（T5 C8）。
+     * 完成只能由 status='done' 表达，progress 到 99 就是这一步的上限。
+     */
+    if (Number(next.progress) >= 100) next.progress = 99
   }
   if (patch.status === 'blocked' && next.finishedAt === null) {
     next.finishedAt = Date.now()
@@ -1272,6 +1280,16 @@ export function deriveAggregates(statuses: readonly StatusEntry[]): {
   }
 
   const total = statuses.length
+  const allDone = total > 0 && done === total
+  /*
+   * [1.5.2] 加权进度在「未全部完成」时不得四舍五入成 100。
+   *
+   * 旧算法直接 `round(progressSum / total)`：11 个 done + 1 个 blocked@95 得到
+   * 100，卡片上就出现「总体进度 100%」旁边还有「1 卡住了 / 11/12 做好了」——
+   * 与截图同类的自相矛盾（T4 实测 A.5）。这里的封顶只作用于展示口径，不影响
+   * 任何计数；全部完成时仍严格为 100，从而与 `done === total` 一一对应。
+   */
+  const raw = total === 0 ? 0 : Math.round(progressSum / total)
   return {
     stats: {
       total,
@@ -1279,7 +1297,7 @@ export function deriveAggregates(statuses: readonly StatusEntry[]): {
       blocked,
       inProgress,
       pending,
-      progress: total === 0 ? 0 : Math.round(progressSum / total),
+      progress: allDone ? 100 : Math.min(99, raw),
     },
     departments: [...departments.values()],
   }
@@ -1309,13 +1327,18 @@ export function computeStats(statuses: any): Stats {
 }
 
 /**
- * Invariant checker for tests and CI; production paths never call it because
- * pure derivation is already self-consistent.
+ * Invariant checker for tests and CI.
  *
  * Returns an empty array when every invariant holds. Each message names the
  * field and the observed value so it can be pasted straight into a report.
+ *
+ * [1.5.2] `phase` 是新增的可选入参：1.4.3 的 I1–I7 只校验计数内部自洽，
+ * 完全不看 `phase` 与 `stats` 的关系，因此「14/14 且 progress=100 却写着
+ * 正在收尾」这种**跨字段**矛盾一路畅通到界面。I8/I9 专门封住这一类：
+ * 只要调用方把本次真正要下发的 phase 传进来，任何「进度与状态文案打架」
+ * 的载荷都会在这里被判为违规，而不是等到用户看截图。
  */
-export function aggregateInvariantViolations(snapshot: PlanSnapshot): string[] {
+export function aggregateInvariantViolations(snapshot: PlanSnapshot, phase?: any): string[] {
   const violations: string[] = []
   const { statuses, stats, departments } = snapshot
 
@@ -1371,17 +1394,96 @@ export function aggregateInvariantViolations(snapshot: PlanSnapshot): string[] {
     violations.push(`I7 各部门 inProgress 之和=${sums.inProgress} 与 stats.inProgress=${stats.inProgress} 不一致`)
   }
 
+  /*
+   * [1.5.2] I8/I9 —— 完成语义跨字段不变量（用户截图那条「100% + 正在收尾」）。
+   *
+   * I8：工作项全部 done ⇔ phase 必须是 done。这是一条双向断言：
+   *     - 全 done 却是 pending/planning/executing/integrating/paused/blocked/degraded
+   *       ⇒ 卡片会同时出现 100% 与进行中文案（本次事故）；
+   *     - phase=done 却还有未完成项 ⇒ 反向矛盾（「已完成」下面挂着没做完的活）。
+   * I9：加权进度与计数同口径：全 done ⇒ 100；未全 done ⇒ 不得为 100。
+   *     旧算法 round(progressSum/total) 让 11 done + 1 blocked@95 算出 100。
+   */
+  if (stats.total > 0) {
+    const allDone = stats.done === stats.total
+    if (allDone && phase !== undefined && phase !== null && phase !== 'done') {
+      violations.push(`I8 stats.done=${stats.done}/${stats.total} 已全部完成，但 phase=${String(phase)} 仍表示未完成`)
+    }
+    if (!allDone && phase === 'done') {
+      violations.push(`I8 phase=done 但 stats.done=${stats.done}/${stats.total} 尚未全部完成`)
+    }
+    if (allDone && stats.progress !== 100) {
+      violations.push(`I9 全部完成但 stats.progress=${stats.progress}`)
+    }
+    if (!allDone && stats.progress >= 100) {
+      violations.push(`I9 未全部完成（${stats.done}/${stats.total}）却显示 stats.progress=${stats.progress}`)
+    }
+  }
+  /*
+   * I10：单个工作项也不能自相矛盾——`in_progress` 意味着「还没做完」，
+   * 它的进度必须 < 100（旧载荷里出现过「正在做 + 100%」，T5 C8）。
+   */
+  for (const item of statuses) {
+    if (item?.status === 'in_progress' && Number(item?.progress) >= 100) {
+      violations.push(`I10 子任务 ${String(item?.subtaskId)} 状态为 in_progress 但 progress=${item?.progress}`)
+    }
+  }
+
   return violations
 }
 
-export function planPhase(statuses: any, resultSeen = false) {
+/**
+ * 计划级阶段，由状态列表唯一决定。
+ *
+ * [1.5.2] 修复「一边 100%、一边正在收尾」的根因。
+ *
+ * 旧实现的最后一步是 `return resultSeen ? 'done' : 'integrating'`：工作项全部
+ * done 时仍要等「结果消息落盘」才晋升终态。问题在于 `resultSeen` 只是**持久化
+ * 回放**才知道的副作用，内存路径（`updateStatus` / `serialisePlan`）拿不到它：
+ *
+ *  - 主 Agent 用 `dsh_workplan_update` 补完最后几项时，phase 永远停在 integrating；
+ *  - 该路径不会再派发，也就永远不会写结果消息，于是 integrating 永久留存；
+ *  - 同期 `stats.done/total` 已是 14/14、百分比 100%，卡片就同时显示
+ *    「100% · 都做完了」和「正在收尾」，并留在「进行中」组（用户截图）。
+ *
+ * 结论：完成语义只能有一个事实源——状态列表。工作项全部完成即计划完成，
+ * 不需要也不允许等另一个副作用来「确认」。`resultSeen` 参数仅为兼容旧调用点保留，
+ * 不再参与判定（旧的 integrating 窗口已由 dispatch 内的 `executing` 覆盖）。
+ */
+export function planPhase(statuses: any, _resultSeen = false) {
   if (statuses.length === 0) return 'pending'
-  if (statuses.every((item: any) => item.status === 'done')) return resultSeen ? 'done' : 'integrating'
+  if (statuses.every((item: any) => item.status === 'done')) return 'done'
   if (statuses.some((item: any) => item.status === 'blocked')) return 'blocked'
   if (statuses.some((item: any) => item.status === 'in_progress' || item.status === 'done')) return 'executing'
   return 'pending'
 }
 
+/**
+ * 把「缓存的 phase」与「由状态列表派生的 phase」对账成唯一结果。
+ *
+ * phase 是缓存（dispatch/预算/取消会写它），statuses 是事实源。只要两者可能
+ * 分叉，就必须在出口处对账，否则同一个会话会因读取路径不同而翻转（实时
+ * integrating / 刷新后 done，T2 场景 B）。
+ *
+ * 规则只有四条，全部可由 `aggregateInvariantViolations` 断言：
+ *  1. 工作项全部 done ⇒ 一定是 done（缓存不得把它拖回任何进行中状态）；
+ *  2. 缓存是 done/integrating 但工作项没全 done ⇒ 缓存过期，回退到派生值；
+ *  3. pending/planning/executing 是「状态列表能直接回答」的轮次状态：一旦
+ *     有工作项开始（派生值不再是 pending），缓存里的旧 pending/planning 必须
+ *     让位；而派生值仍是 pending 时保留缓存（dispatch 刚开始、状态尚未落盘）。
+ *  4. 其余情况保留缓存的轮次状态（paused/cancelled/blocked/degraded）——
+ *     它们携带状态列表里没有的信息（预算暂停、用户取消）。
+ */
+export function reconcilePhase(phase: any, statuses: any) {
+  const derived = planPhase(statuses)
+  if (derived === 'done') return 'done'
+  if (phase === 'done' || phase === 'integrating') return derived
+  if (phase === 'pending' || phase === 'planning' || phase === 'executing') {
+    return derived === 'pending' ? phase : derived
+  }
+  return phase ?? derived
+}
+
 export function nextReadyInStage(plan: any, statuses: any[], stageId: string) {
   const byId = new Map(statuses.map((item: any) => [item.subtaskId, item]))
   const stage = plan.stages.find((item: any) => item.id === stageId)