pmem-ai 0.6.0 → 0.6.2

package/docs/v0.6.1 pre-design.md

@@ -0,0 +1,566 @@
+# v0.6.1 前置设计决策
+
+本文档记录 pmem v0.6.1 开工前的产品与技术决策。v0.6.1 的核心定位：
+
+> **Actionable Update Suggestions**
+>
+> v0.6 已经完成 Agent-native Workflow Polish 并发布到 npm (`pmem-ai@0.6.0`)。
+>
+> v0.6.1 不新增大型子系统，不改变 memory schema，不做 embedding、MCP/REST、Graph UI、telemetry 或远程服务。
+> v0.6.1 只解决一个真实使用中暴露出来的急痛点：`pmem update --suggest` 在长期项目里输出过于冗长，重复 dirty flags 和历史建议会让 agent / 用户误判当前记忆仍有问题。
+>
+> v0.6.1 要回答的唯一问题：**pmem 能否把 update suggestions 从“完整事件日志”变成“可行动的当前摘要”，并与 verify 语义保持一致？**
+
+---
+
+## 一、背景：v0.6 后真实使用反馈
+
+用户反馈显示，`pmem update --suggest --format json` 在长期项目中存在信噪比问题：
+
+| 现象 | 影响 |
+|------|------|
+| 一个实际工作变更触发大量历史 dirty flags | Agent 难以判断当前任务真正要处理什么 |
+| 同一 card 因同类原因重复出现很多次 | 输出体积膨胀，重复建议掩盖有效建议 |
+| 当前会话项与历史遗留项混杂 | 用户无法快速判断哪些是当前相关 |
+| `--format json` 机器友好但人类调试困难 | 调试时需要手工归并、筛选、推断 |
+| `pmem verify` 已 100/100，但 `update --suggest` 仍有大量建议 | 用户误以为 memory consistency 仍有问题 |
+| dirty flags 缺少过期 / 聚合 / 生命周期 | 长期项目噪声持续累积 |
+
+一句话结论：
+
+> pmem 当前的记忆一致性能力是有价值的，但 `update --suggest` 缺少去重、分级和生命周期边界，导致长会话 / 多阶段项目里输出会快速膨胀。
+
+v0.6.1 的目标是先修输出语义和行动性，不在 patch release 中引入完整 dirty lifecycle 子系统。
+
+---
+
+## 二、v0.6.1 产品目标
+
+### 一句话目标
+
+> **`pmem update --suggest` 默认展示当前可行动摘要，隐藏重复和历史噪声，并明确区分 verify blocking 问题与非阻塞维护建议。**
+
+### 用户对象
+
+| 用户 | 需求 |
+|------|------|
+| Code agent | 能从 JSON 中直接判断当前是否需要行动、是否影响 verify、是否只是历史建议 |
+| 项目维护者 | 能用 compact 输出快速看懂当前 dirty 状态 |
+| 调试者 | 能按需查看 history / duplicates，而不是默认被历史噪声淹没 |
+| 长期项目使用者 | 不因旧 dirty flags 反复出现而失去对 pmem 的信任 |
+
+### 成功标准
+
+1. 同一 `target + reason + matched_file` 的 dirty flag / suggestion 默认聚合展示，并保留 `count`。
+2. suggestions 输出包含 severity 和 verify 相关字段：`blocking | warning | info`、`blocks_verify`。
+3. 默认输出区分 `blocking_for_verify`、`current_suggestions`、`historical_dirty_flags`。
+4. 默认隐藏重复历史项，提供 `--include-history` 查看。
+5. `--format compact` 输出能让人类 10 秒内看懂当前是否需要行动。
+6. `--format json` 输出保留机器可解析结构，不再只是扁平数组。
+7. 当 `pmem verify` 已无 blocking consistency issues 时，`update --suggest` 明确说明没有阻塞项。
+8. 不引入完整 `pmem dirty` 子命令或 dirty lifecycle 状态机；这些进入 v0.6.2。
+
+---
+
+## 三、范围划分
+
+### P0 — v0.6.1 必须完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | suggestion 去重聚合 | 按 `target + reason + matched_file` 聚合，输出 `count` 和 `sources` |
+| 2 | 输出分级 | 区分 `blocking_for_verify`、`current_suggestions`、`historical_dirty_flags` |
+| 3 | severity 字段 | 每条 suggestion 带 `severity`、`blocks_verify`、`is_historical`、`is_duplicate` |
+| 4 | compact summary | `--format compact` 输出 affected cards、blocking 数、hidden duplicates、hidden history |
+| 5 | JSON 结构化摘要 | `--format json` 输出 `summary` + `groups`，便于 agent 决策 |
+| 6 | `--include-history` | 默认隐藏历史 dirty flags；显式 flag 才展示完整历史组 |
+| 7 | verify/suggest 语义对齐 | 共享 verify 检查逻辑，避免 verify 100/100 时 suggest 看起来仍阻塞 |
+| 8 | E2E 噪声场景 | 构造重复 dirty flags，验证默认输出聚合和隐藏历史 |
+
+### P1 — v0.6.1 可选，优先推迟到 v0.6.2
+
+| 功能 | 说明 |
+|------|------|
+| `pmem dirty list` | dirty flags 独立查询命令 |
+| `pmem dirty resolve --auto` | 自动标记已解决 dirty flags |
+| `pmem dirty prune --older-than 7d` | 清理历史 dirty flags |
+| 完整 dirty lifecycle | `open / resolved / superseded / ignored / archived` |
+| `--current-session` / `--since-session` | 依赖 dirty lifecycle 和 session 语义，先不做 P0 |
+| auto-cleanup | 依赖 lifecycle 状态机，放到 v0.6.2 |
+
+### 明确不做
+
+| 不做 | 原因 |
+|------|------|
+| 改变 dirty_flags SQLite schema | v0.6.1 是 patch release，优先复用现有 `resolved_at` |
+| 自动删除历史 flags | 删除是不可逆操作，需 lifecycle 设计支撑 |
+| 新增远程 / 服务化能力 | 与本次反馈无关 |
+| 改变 exit code 协议 | `update --suggest` exit 1 仍表示有建议，不是错误 → **v0.6.2 已变更：exit 1 不再作为 workflow signal** |
+
+---
+
+## 四、输出语义设计
+
+### 1. 新核心概念
+
+| 概念 | 定义 |
+|------|------|
+| blocking_for_verify | 当前会导致 `pmem verify` warning/error 的一致性问题 |
+| current_suggestions | 当前仍值得 agent 处理，但不阻塞 verify 的建议 |
+| historical_dirty_flags | 历史遗留、重复或已不影响当前一致性的 dirty flags |
+| duplicate_hidden | 被聚合隐藏的重复 dirty flag 数 |
+| historical_hidden | 默认未展示的历史项数 |
+
+`update --suggest` 不再把所有 unresolved dirty flags 等价展示。它应该回答：
+
+1. 是否有阻塞当前 verify 的问题。
+2. 当前真正需要处理哪些 cards。
+3. 隐藏了多少重复 / 历史噪声。
+4. 如何查看完整历史。
+
+### 2. compact 输出
+
+无阻塞但有历史项：
+
+```txt
+Memory update suggestions
+
+Blocking for verify: 0
+Current suggestions: 0
+Historical hidden: 7
+Duplicate flags hidden: 18
+
+No blocking memory consistency issues.
+Historical suggestions are available with --include-history.
+```
+
+有当前建议：
+
+```txt
+Memory update suggestions
+
+Affected cards: 3
+Blocking for verify: 1
+Current suggestions: 2
+Historical hidden: 7
+Duplicate flags hidden: 18
+
+Blocking:
+- module.runtime_executor (stale_memory, crates/sprflow-runtime/src/executor.rs, count 4)
+
+Current:
+- trace.phase2_evaluation_accepted_2026-05-21 (file_changed, count 3)
+
+Next:
+- Update or confirm affected cards with pmem update --confirm -s "<summary>" -n "<next step>"
+- Use --include-history to inspect older dirty flags.
+```
+
+### 3. JSON 输出
+
+建议结构：
+
+```json
+{
+  "summary": {
+    "affected_cards": 3,
+    "blocking": 1,
+    "warning": 2,
+    "info": 0,
+    "duplicates_hidden": 18,
+    "historical_hidden": 7,
+    "verify_blocking": true
+  },
+  "message": "1 blocking memory consistency issue and 2 current suggestion(s).",
+  "next_steps": [
+    "Update or confirm affected cards with pmem update --confirm -s \"<summary>\" -n \"<next step>\"",
+    "Use --include-history to inspect older dirty flags."
+  ],
+  "groups": {
+    "blocking_for_verify": [
+      {
+        "target": "module.runtime_executor",
+        "reason": "stale_memory",
+        "matched_file": "crates/sprflow-runtime/src/executor.rs",
+        "count": 4,
+        "severity": "blocking",
+        "blocks_verify": true,
+        "is_duplicate": false,
+        "is_historical": false,
+        "created_at_first": "2026-05-22T08:00:00.000Z",
+        "created_at_last": "2026-05-22T09:30:00.000Z"
+      }
+    ],
+    "current_suggestions": [],
+    "historical_dirty_flags": []
+  }
+}
+```
+
+当未传 `--include-history` 时，`historical_dirty_flags` 可以为空数组，但 `summary.historical_hidden` 必须保留。
+
+### 4. exit code
+
+保留现有协议：
+
+| 状态 | exit code |
+|------|-----------|
+| 无 blocking、无 current suggestions、无可展示历史 | 0 |
+| 有 blocking 或 current suggestions | 1 |
+| 仅有 hidden historical suggestions | 0 |
+| 命令错误 | 2 |
+
+这样可以避免“verify 已通过，但历史项导致 agent 以为仍需处理”的误判。
+
+---
+
+## 五、技术方案
+
+### 1. 共享 verify 检查逻辑
+
+总工建议的两条路径：
+
+| 路径 | 评价 |
+|------|------|
+| A. suggest 内联 verify 检查 | 实现快，但会复制 verify stale-memory 逻辑，未来漂移 |
+| B. 抽出共享检测函数 | 更符合长期维护，能真正对齐 verify/suggest 语义 |
+
+v0.6.1 采用 **B：共享检测函数**。
+
+建议新增：
+
+```txt
+src/core/consistency.ts
+```
+
+核心职责：
+
+```ts
+export interface ConsistencyIssue {
+  type: string;
+  severity: 'blocking' | 'warning' | 'info';
+  card_id?: string;
+  file_path?: string;
+  message: string;
+}
+
+export function checkStaleMemory(pmemPath: string): ConsistencyIssue[];
+```
+
+`verify.ts` 和 `update.ts` 都调用这层函数：
+
+- `verify.ts` 负责把 issues 转成 verify 输出和 score。
+- `update.ts` 负责把 issues 与 dirty flags / suggestions 交叉归类。
+
+v0.6.1 不必一次性迁移 verify 的全部 10 项检查，P0 只抽出与 `stale_memory` / dirty suggestion 语义相关的部分。
+
+### 2. Dirty flag 聚合
+
+当前 `dirty_flags` 表已有：
+
+```txt
+scope
+target
+reason
+created_at
+resolved_at
+session_id
+```
+
+v0.6.1 不改 schema。聚合 key：
+
+```txt
+target + reason + matched_file
+```
+
+`matched_file` 来源优先级：
+
+1. dirty flag reason payload 中已有文件信息时使用它。
+2. 若 reason 只是 `file_changed`，从 card 的 `source_files` / paths 反查。
+3. 无法确定时为 `null`，聚合 key 使用 `target + reason + null`。
+
+聚合输出字段：
+
+```ts
+interface AggregatedSuggestion {
+  target: string;
+  reason: string;
+  matched_file: string | null;
+  count: number;
+  severity: 'blocking' | 'warning' | 'info';
+  blocks_verify: boolean;
+  is_duplicate: boolean;
+  is_historical: boolean;
+  created_at_first: string;
+  created_at_last: string;
+  sources: Array<{
+    scope: string;
+    target: string;
+    reason: string;
+    created_at: string;
+    session_id?: string | null;
+  }>;
+}
+```
+
+### 3. Historical 判定
+
+v0.6.1 不引入完整 lifecycle，因此 historical 是输出层分类，不写回 DB。
+
+建议判定规则：
+
+| 条件 | 分类 |
+|------|------|
+| 对应 verify issue | `blocking_for_verify` |
+| dirty flag created_at 在最近 active / latest session 之后 | `current_suggestions` |
+| dirty flag target 与当前 changed files 有直接 source_files 关联 | `current_suggestions` |
+| 聚合组 count > 1 且没有 verify issue | duplicate hidden / historical |
+| created_at 早于最近 update_log 或 session end，且不阻塞 verify | `historical_dirty_flags` |
+| 无法判断但不阻塞 verify | `current_suggestions`，避免误藏 |
+
+原则：**宁可把不确定项留在 current，也不要把可能需要处理的项藏进 history。**
+
+### 4. CLI option
+
+`pmem update --suggest` 新增：
+
+```bash
+--include-history
+```
+
+现有：
+
+```bash
+--format compact|json
+```
+
+行为：
+
+| 命令 | 行为 |
+|------|------|
+| `pmem update --suggest` | 默认 compact，隐藏历史 |
+| `pmem update --suggest --format compact` | 同上 |
+| `pmem update --suggest --format json` | 输出 summary + groups，隐藏 history details |
+| `pmem update --suggest --include-history` | compact 中展示 historical section |
+| `pmem update --suggest --format json --include-history` | JSON 中填充 `groups.historical_dirty_flags` |
+
+### 5. 与 `pmem verify` 对齐
+
+如果共享 consistency check 没有 blocking issues，`update --suggest` 必须输出：
+
+```txt
+No blocking memory consistency issues.
+```
+
+JSON：
+
+```json
+{
+  "summary": {
+    "verify_blocking": false,
+    "blocking": 0
+  },
+  "message": "No blocking memory consistency issues."
+}
+```
+
+注意：`verify` 的 score 可能仍有非 dirty 类型 warning。v0.6.1 只保证 `update --suggest` 不把非阻塞历史 dirty flags 表达成 blocking issue。
+
+---
+
+## 六、E2E 测试设计
+
+### E2E 1：重复 dirty flags 聚合
+
+流程：
+
+```bash
+pmem init v061-duplicates --description "x" --stage "y" --next "z"
+mkdir -p src .pmem/modules
+# 写入含 source_files 的 module card
+pmem rebuild
+# 多次修改同一个 source file 并 mark-dirty --auto
+pmem update --suggest --format json
+```
+
+验收：
+
+- 同一 target/reason/matched_file 只出现一个聚合项。
+- 聚合项 `count > 1`。
+- `summary.duplicates_hidden > 0`。
+
+### E2E 2：verify 通过但有历史 dirty flags
+
+流程：
+
+```bash
+pmem verify
+pmem update --suggest --format compact
+pmem update --suggest --format json
+```
+
+验收：
+
+- compact 输出 `No blocking memory consistency issues.`。
+- JSON `summary.verify_blocking === false`。
+- 仅历史项时 exit code 为 0。
+
+### E2E 3：include-history
+
+流程：
+
+```bash
+pmem update --suggest --format json
+pmem update --suggest --format json --include-history
+```
+
+验收：
+
+- 默认 `groups.historical_dirty_flags` 为空或省略详情。
+- `--include-history` 填充 historical details。
+- 两者 summary 中 hidden count 一致。
+
+### E2E 4：blocking issue 分组
+
+流程：
+
+```bash
+# 构造 source_files 指向已变更但 card 未更新的 stale memory
+pmem verify
+pmem update --suggest --format json
+```
+
+验收：
+
+- 对应 card 进入 `groups.blocking_for_verify`。
+- `severity === "blocking"`。
+- `blocks_verify === true`。
+- exit code 为 1。
+
+---
+
+## 七、文档更新
+
+### README.md
+
+新增：
+
+- `update --suggest` 输出结构说明。
+- `--include-history` 使用说明。
+- verify/suggest 关系说明。
+- exit code 中补充“仅 hidden history 不返回 1”。
+
+### docs/usage.md
+
+补充长期项目建议：
+
+```bash
+pmem update --suggest --format compact
+pmem update --suggest --format json --include-history
+```
+
+### CHANGELOG.md
+
+新增 `0.6.1 - Actionable Update Suggestions` planned / released section。
+
+### release checklist
+
+新增 `docs/release-checklist-v0.6.1.md`，聚焦：
+
+- version bump 到 `0.6.1`
+- compact/json output snapshot
+- duplicate aggregation E2E
+- verify/suggest alignment E2E
+- npm publish smoke
+
+---
+
+## 八、实现顺序
+
+```txt
+Step 0: 冻结 v0.6.1 pre-design（本文档）
+  ↓
+Step 1: 抽出 consistency check
+  - src/core/consistency.ts
+  - verify.ts 调用共享 stale-memory check
+  ↓
+Step 2: 聚合 dirty flags / suggestions
+  - AggregatedSuggestion 类型
+  - target + reason + matched_file key
+  - duplicates_hidden / historical_hidden summary
+  ↓
+Step 3: 输出结构改造
+  - compact summary
+  - json summary + groups
+  - severity / blocks_verify / is_historical
+  ↓
+Step 4: CLI option
+  - --include-history
+  - exit code 调整：仅 hidden history 返回 0
+  ↓
+Step 5: E2E / docs / release checklist
+```
+
+---
+
+## 九、验收清单
+
+### 产品验收
+
+- [ ] 长期项目中重复 dirty flags 不再默认刷屏。
+- [ ] 人类能从 compact 输出看出当前是否有 blocking issue。
+- [ ] Agent 能从 JSON `summary` 和 `groups` 判断下一步。
+- [ ] verify 100/100 时 suggest 不再表现得像还有阻塞问题。
+- [ ] 历史项可通过 `--include-history` 查看。
+
+### 工程验收
+
+- [ ] `npm test` 通过。
+- [ ] `npm run build` 通过。
+- [ ] duplicate aggregation E2E 通过。
+- [ ] verify/suggest alignment E2E 通过。
+- [ ] include-history E2E 通过。
+- [ ] exit code snapshot 与文档一致。
+
+### 发布验收
+
+- [ ] `package.json` version 为 `0.6.1`。
+- [ ] `package-lock.json` root version 为 `0.6.1`。
+- [ ] `src/index.ts` Commander version 为 `0.6.1`。
+- [ ] `CHANGELOG.md` 包含 `0.6.1`。
+- [ ] npm pack / install smoke 通过。
+
+---
+
+## 十、v0.6.1 最终决策表
+
+| 问题 | 最终决策 |
+|------|---------|
+| v0.6.1 主线 | Actionable Update Suggestions |
+| 是否改 dirty_flags schema | 不改 |
+| 是否新增 `pmem dirty` 子命令 | 不做，推迟到 v0.6.2 |
+| 是否做完整 dirty lifecycle | 不做，推迟到 v0.6.2 |
+| 是否做 `--current-session` | 不做 P0，等待 lifecycle 设计 |
+| 是否 auto-cleanup | 不做 P0，避免无 lifecycle 的隐式删除 |
+| 是否改变 exit code 协议 | 不改变主协议；仅 hidden history 不触发 exit 1 |
+| 最重要交付 | 去重聚合 + 分级输出 + compact summary + verify/suggest 对齐 |
+| 成功定义 | `update --suggest` 默认输出当前可行动事项，而不是历史事件日志 |
+
+---
+
+## 十一、v0.6.1 一句话定义
+
+> **pmem v0.6.1 是一次针对 `update --suggest` 的行动性补丁：把重复和历史噪声折叠起来，把 verify-blocking 问题凸显出来，让 agent 和用户都能清楚判断当前是否需要处理记忆。**
+
+更工程化：
+
+```txt
+pmem v0.6.1 =
+  pmem-ai@0.6.0
++ aggregated suggestions
++ severity and blocks_verify metadata
++ compact actionable summary
++ hidden historical noise by default
++ --include-history
++ shared verify/suggest stale-memory check
+```