pmem-ai 0.6.0 → 0.6.2

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

@@ -0,0 +1,657 @@
+# v0.6.2 前置设计决策
+
+本文档记录 pmem v0.6.2 开工前的产品与技术决策。v0.6.2 的核心定位：
+
+> **Real-User Friction Fixes**
+>
+> v0.6.1 已发布到 npm (`pmem-ai@0.6.1`) 并进入真实用户观察期。
+>
+> 2026-05-23 收到首份重度用户反馈（voxo v1.0 项目，25 张卡片、27 条 trace、完整 P0→发布周期）。
+>
+> v0.6.2 不新增大型子系统，不改变 memory schema，不做 embedding、MCP/REST、Graph UI、telemetry 或远程服务。
+> v0.6.2 只解决真实用户反馈中暴露的三个 P0 摩擦点：**锁竞争修复、卡片大小可配置、跨卡片批量重命名**。外加从同一份反馈中提取的四项低风险体验改进。
+>
+> v0.6.2 要回答的唯一问题：**pmem 能否消除重度用户在真实项目中遭遇的 top-3 摩擦，让"从 init 到发布"的完整生命周期不被工具自身打断？**
+
+---
+
+## 一、背景：v0.6.1 首份重度用户反馈
+
+2026-05-23，voxo v1.0 项目 CTO 提交了 `pmem-0.6.1-feedback.md`（已存档为 trace 卡片）。这是 pmem 在真实跨平台 CLI 项目（从零到发布）中作为唯一项目记忆系统的首份完整实战报告。
+
+### 已验证正确的设计（4 项）
+
+| 设计决策 | 用户原话 | 结论 |
+|----------|---------|------|
+| Markdown 卡片是唯一真相源 | "这个设计选择是决定性的" | 坚持 |
+| 六种卡片类型 | "刚好覆盖，不会少也不会多到让人选择困难" | 不增减 |
+| `pmem ask` 图展开搜索 | "这个图展开能力在实际使用中比我想象的有用" | 价值被低估 |
+| Claude Code 集成开箱体验 | "新的 agent 进来两条命令就能恢复全部上下文" | 做对了 |
+
+### 暴露的摩擦点（6 项，按影响排序）
+
+| # | 问题 | 当前代码状况 | 用户影响 |
+|---|------|-------------|---------|
+| 1 | SQLite 锁竞争 | `src/core/fs.ts:66-103`，busy-wait 3s 超时，stale 60s 从不自动清理，无查看/强制释放命令 | `pmem update --confirm` 失败 3 次，用户以为数据会丢 |
+| 2 | 卡片大小限制过于激进 | `src/core/manifest.ts:114`，硬编码 module 1200/decision 800/task 600 token，不可配置 | 写分 P 计划被打 `card_too_large` 警告 2 次 |
+| 3 | 跨卡片批量重命名缺失 | 无此命令 | 项目改名时手动 grep + sed + rebuild 6 个文件 |
+| 4 | `pmem recall` 输出随卡片线性增长 | 无 `--since` 过滤 | 25 张卡片已感觉长，50-100 张时 2000 token 不够 |
+| 5 | `pmem update --suggest` exit code 1 | 设计决策，文档写了 "workflow signal"，但用户心理和 CI 都不认 | 每次看到 exit 1 心里一紧 |
+| 6 | session 状态偶尔丢失 | `src/commands/session.ts:77-82`，报 "No active pmem session found" | 影响 session end 可用性 |
+
+### 用户自己排的优先级
+
+> **锁竞争修复 > 卡片大小可配置 > 批量重命名**
+
+### 愿望清单（4 项）
+
+1. `pmem health`：更面向用户的一键诊断（现有 `pmem doctor` 用户觉得不够直观）
+2. 卡片模板生成：`pmem new decision "标题"` 自动生成 YAML frontmatter
+3. Frontmatter 创建时校验：必填字段缺失立即警告，不等 rebuild 静默跳过
+4. Git hook 集成：`pmem integration install git-hooks`
+
+---
+
+## 二、v0.6.2 产品目标
+
+### 一句话目标
+
+> **消除重度用户在真实项目中遭遇的 top-3 摩擦，让 pmem 不成为自身工具链的阻塞点。**
+
+### 用户对象
+
+| 用户 | 核心诉求 |
+|------|---------|
+| 重度项目使用者 | 锁不卡、卡片不被大小限制打断、改项目名不用手动批量 grep |
+| Code agent | 锁竞争时的错误信息可直接指导恢复操作 |
+| 新用户 | 创建卡片时有模板可用、必填字段当场提示 |
+
+### 成功标准
+
+1. `pmem update --confirm` 在锁竞争场景下不再需要用户手动 `rebuild --full` 才能恢复。
+2. stale lock（>60s）在获取锁前自动检测并清理，用户无感知。
+3. `pmem verify` 提供 `--fix-locks` 选项，可一键清理僵死锁。
+4. 卡片大小限制可通过 manifest `card_policy.max_tokens` 自定义，verify 提供 `--relaxed` 模式。
+5. `pmem rename --find "old" --replace "new"` 默认预览 diff 不写入，`--write` 时执行全文替换。
+6. `pmem recall --since 7d` 只返回近期变更的卡片。
+7. `pmem update --suggest` 在有建议时不再返回 exit code 1。
+8. `pmem new <type> "<title>"` 自动生成符合规范的卡片骨架。
+9. `pmem integration install git-hooks` 可安装 pre-commit verify hook。
+10. `pmem doctor` 新增 lock status 检查项。
+
+---
+
+## 三、scope 分级
+
+### P0 — 必须修复（来自反馈 top-3）
+
+| 功能 | 说明 | 复杂度 |
+|------|------|--------|
+| 锁竞争修复 | stale lock 自动清理 + `--fix-locks` + 错误消息增强 + doctor 锁检查 | 低 |
+| 卡片大小可配置 | 尊重 manifest `card_policy.max_tokens` + verify `--relaxed` 模式 + 文档 | 低 |
+| 批量重命名 | `pmem rename --find/--replace [--write]`（默认预览） | 中 |
+
+### P1 — 强烈建议（来自反馈其余项 + 愿望清单）
+
+| 功能 | 说明 | 复杂度 |
+|------|------|--------|
+| `recall --since` | 按时间过滤 recall 输出，时间契约已补全（§5.1） | 低 |
+| exit code 修正 | `update --suggest`/`status`/`distill --suggest` 有结果时 exit 0，兼容性方案已通过（§5.2） | 低（代码）、中（文档） |
+| 卡片模板生成 | `pmem new <type> "<title>"` | 低 |
+| Frontmatter 创建时校验 | `pmem new` 时当场校验必填字段 | 低 |
+| Git hook 集成 | `pmem integration install git-hooks` | 低 |
+| session 健壮性排查 | 调查 session 丢失根因 + 修复 | 中 |
+
+> **注：** `pmem doctor` 锁检查已在 P0 中随锁竞争修复一并实现，不再出现在 P1 列表中。
+
+### 明确不做（推迟到 v0.7+）
+
+- 完整 dirty lifecycle（`open / resolved / superseded / ignored / archived`）—— v0.6.1 已推迟
+- `pmem dirty list/resolve/prune` —— v0.6.1 已推迟
+- `pmem health` 独立命令 —— 用 `pmem doctor` 增强替代，不新建命令
+- embedding / semantic search
+- MCP Server / REST API
+- Graph UI
+- telemetry
+- 多项目 workspace
+
+### P0 完成状态
+
+| 任务 | 状态 | 验证 |
+|------|------|------|
+| 锁竞争修复 + `verify --fix-locks` + `doctor` lock 检查 | ✅ 已实现并验收 | E2E 覆盖 stale/active lock 全部场景 |
+| `verify --relaxed` + card policy 文档化 + 默认 token 上调 | ✅ 已实现并验收 | E2E 覆盖 oversized 检测、relaxed 模式、manifest 自定义 |
+| `pmem rename` 默认预览 + `--write` | ✅ 已实现并验收 | E2E 覆盖 preview/write/rebuild/verify + frontmatter hash 不变 |
+
+P0 验收通过（CTO，2026-05-23）。
+
+**已知非阻塞 P2：** `rename.ts` 的 `splitFrontmatter()` 对 body 做了 `trimStart()`，因此"完全保留 body 原始空白"的说法不严谨。不影响 frontmatter hash、不影响 P0 安全边界。后续 polish 可改为记录 frontmatter end 后的原始 body slice。
+
+---
+
+## 四、P0 详细设计
+
+### 4.1 锁竞争修复
+
+**现状：**
+
+```
+src/core/fs.ts:
+  acquireLock()  → mkdirSync 重试 3s，失败返回 false
+  releaseLock()  → rmdirSync
+  isLockStale()  → stat mtime > 60s 判定为 stale（存在但从未被调用）
+  breakLock()    → 等同于 releaseLock（存在但从未暴露给 CLI）
+```
+
+三个问题：
+1. `isLockStale` 已实现但**没有任何调用方**——获取锁前不检查 stale。
+2. `breakLock` 已实现但**没有 CLI 入口**——用户无法手动清理。
+3. 获取锁失败时错误消息是通用的 `Failed to acquire pmem lock`，不含排查建议。
+
+**修改点：**
+
+**a) `acquireLock` 自动清理 stale lock**
+
+在 `acquireLock` 获取锁之前，先检查现有锁是否 stale，若 stale 则自动 break 再重试：
+
+```
+acquireLock() 逻辑变更：
+  1. try mkdirSync → 成功则返回 true（不变）
+  2. catch → 检查现有锁是否 isLockStale(lockPath, 60s)
+     a. 若 stale → breakLock() → 重试 mkdirSync
+     b. 若不 stale → 继续 busy-wait（不变）
+```
+
+**b) `pmem verify --fix-locks`**
+
+verify 新增检查项：检测 `.pmem/.lock` 是否存在且 stale，若存在则：
+- `--fix-locks` 时自动清理
+- 无 `--fix-locks` 时报告 warning + 修复建议
+
+**c) 错误消息增强**
+
+```
+// 之前
+Failed to acquire pmem lock
+
+// 之后
+Failed to acquire pmem lock after 3s.
+  The lock at .pmem/.lock may be held by another pmem process.
+  → Run: pmem verify --fix-locks  (to check and clean stale locks)
+  → Or:  pmem doctor              (to diagnose lock status)
+  If no other pmem process is running, delete .pmem/.lock manually.
+```
+
+**d) `pmem doctor` 新增锁检查**
+
+在第 8 项 integrations 之前插入锁状态检查：
+
+```
+Lock: ✓ No stale lock.
+Lock: ⚠ Stale lock detected at .pmem/.lock (age: 72s). Run: pmem verify --fix-locks
+Lock: ✗ Active lock held at .pmem/.lock (age: 2s). Another pmem process may be running.
+```
+
+### 4.2 卡片大小可配置
+
+**现状：**
+
+`src/core/manifest.ts:114` 定义默认值，`src/commands/verify.ts:167` 从 `manifest.card_policy.max_tokens[card.type]` 读取。
+
+**关键发现：** verify 已经读取用户 manifest 中的 `card_policy.max_tokens`，用户手动编辑 manifest.yml 即可修改限制。问题是：
+1. 这没有被文档化
+2. 没有简单的方式临时放宽限制
+3. 默认值对重度文档场景偏小
+
+**修改点：**
+
+**a) 提供 `--relaxed` 模式**
+
+```bash
+pmem verify --relaxed    # 所有 max_tokens 临时 ×2
+```
+
+实现：verify 读 `policy.max_tokens` 后，若 `--relaxed` 则每个值 ×2 再比较。
+
+**b) 将 `card_policy` 配置文档化**
+
+在 `pmem verify` 的 `card_too_large` 警告信息中加入修改指引：
+
+```
+Card "breakdown_p0_plan" (task) exceeds 600 token limit (~920 tokens).
+  → Edit .pmem/manifest.yml → card_policy → max_tokens → task to raise the limit.
+  → Or run: pmem verify --relaxed (temporarily doubles all limits).
+  → Or run: pmem distill --suggest-splits (check if this card can be split).
+```
+
+**c) 调整默认值（保守上调）**
+
+当前默认值偏保守，基于用户反馈适度上调：
+
+| 类型 | 旧默认 | 新默认 |
+|------|--------|--------|
+| module | 1200 | 1200（不变） |
+| feature | 1000 | 1000（不变） |
+| decision | 800 | 1000 |
+| task | 600 | 800 |
+| trace | 1000 | 1000（不变） |
+
+decision 和 task 各上调 200 token。不改 manifest schema，只改 `getDefaultManifest` 中的默认值。
+
+### 4.3 批量重命名
+
+**新命令：** `pmem rename`
+
+```bash
+pmem rename --find <pattern> --replace <replacement>          # 默认 dry-run，只预览
+pmem rename --find <pattern> --replace <replacement> --write  # 显式写入
+```
+
+**安全设计：默认 dry-run**
+
+`pmem rename` 不提供 `--dry-run` flag——默认行为就是 dry-run。真实写入必须通过显式 `--write` flag 确认。这避免了用户（或 agent）在未预览 diff 的情况下误改卡片内容。
+
+```
+无 --write → 扫描匹配文件 → 打印 diff 预览 → 输出 "N files would be changed. Add --write to apply." → exit 0
+有 --write → 扫描匹配文件 → atomicWrite 每个变更文件 → pmem rebuild --changed → 输出 "N files changed, M occurrences replaced." → exit 0
+```
+
+**行为：**
+
+1. 扫描所有 `.pmem/**/*.md` 卡片文件的 **body 文本**（不碰 frontmatter 的 `id`、`aliases` 等结构化字段，不碰文件名）
+2. 对 body 内容执行 `String.prototype.replaceAll(pattern, replacement)`
+3. 默认模式（无 `--write`）：显示 diff 预览，不写入，exit 0
+4. `--write` 模式：atomicWrite 每个变更文件 → 自动 rebuild --changed
+
+**设计原则：**
+- 只替换 body，不碰 frontmatter 结构字段。避免误改 `id` 导致图边断裂。
+- 不重命名文件。卡片 ID 保持稳定。
+- **默认 dry-run。** 任何不熟悉此命令的用户（或 agent）跑 `pmem rename` 不会产生副作用。
+- 修改 frontmatter 需求明确超出 scope，不提供 `--include-frontmatter` flag。若用户需要改 ID/alias，引导他们手动编辑卡片。
+
+**实现要点：**
+
+```
+src/commands/rename.ts:
+  1. loadManifest → 获取 source_of_truth.card_globs
+  2. glob 匹配所有卡片文件
+  3. 对每个文件：
+     a. 解析 frontmatter + body
+     b. body.replaceAll(find, replace)
+     c. 若 body 有变更 → 记录 diff
+  4. 若 !options.write:
+     a. 打印 diff 预览
+     b. 输出 "N files would be changed. Add --write to apply." 
+     c. exit 0
+  5. 若 options.write:
+     a. atomicWrite 每个变更文件
+     b. 确保 frontmatter 部分逐字节不变（仅 body 变更，frontmatter hash 不变）
+     c. pmem rebuild --changed
+  6. 输出：N files changed, M occurrences replaced
+```
+
+**CLI 注册：**
+
+```typescript
+program
+  .command('rename')
+  .description('Preview or apply batch text replacement in memory card bodies')
+  .requiredOption('--find <pattern>', 'Text to find in card bodies')
+  .requiredOption('--replace <replacement>', 'Replacement text')
+  .option('--write', 'Apply changes (default is dry-run preview only)', false)
+  .action(renameCommand);
+```
+
+---
+
+## 五、P1 详细设计
+
+### 5.1 `pmem recall --since`
+
+recall 新增可选时间过滤参数：
+
+```bash
+pmem recall --since 7d     # 最近 7 天
+pmem recall --since 24h    # 最近 24 小时
+pmem recall --since 1w     # 最近 1 周
+```
+
+无效格式（如 `--since abc`、`--since 7x`）返回 exit 2 并输出清晰错误信息。
+
+**时间来源契约**
+
+当前 `rebuild` 将 `cards.updated_at` 设为 `fm.updated ?? null`（`src/commands/rebuild.ts:131`）。若卡片 frontmatter 无 `updated` 字段，`updated_at` 为 `null`，导致 `--since` 过滤漏掉近期实际有变更的卡片。
+
+修正方案——时间来源优先级：
+
+```
+1. frontmatter.updated  （用户显式声明的时间，最可信）
+2. 文件 mtime           （文件系统修改时间，fallback）
+3. rebuild timestamp    （本次 rebuild 的时间，最终兜底）
+```
+
+**时间比较契约（钉死）：**
+
+| 层 | 格式 | 说明 |
+|----|------|------|
+| `cards.updated_at` | ISO 8601 字符串 (`2026-05-23T08:30:00.000Z`) | rebuild 阶段写入 |
+| threshold | ISO 8601 字符串 | TS 解析 `--since` 值后计算 |
+| SQL | `WHERE cards.updated_at >= ?` | 参数化查询，字符串字典序比较 |
+
+**为什么不可以用 SQLite `datetime()` 比较：**
+
+SQLite `datetime('now', '-7 days')` 返回 `YYYY-MM-DD HH:MM:SS`，与 ISO 8601 `2026-05-23T08:30:00.000Z` 格式不同。虽然字符串字典序碰巧可比较，但不构成契约。设计选择：**在 TS 层解析时间、计算 threshold ISO 字符串、参数化传入 SQL**，彻底避免格式依赖。
+
+**--since 解析规则：**
+
+```typescript
+function parseSince(since: string): string | null {
+  const match = since.match(/^(\d+)([hdw])$/);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  const ms = unit === 'h' ? value * 3600000
+           : unit === 'd' ? value * 86400000
+           : unit === 'w' ? value * 604800000
+           : 0;
+  if (ms === 0) return null;
+  return new Date(Date.now() - ms).toISOString();
+}
+```
+
+无效格式 → `null` → `console.log('Invalid --since format...')` → `process.exit(2)`。
+
+实现方式：
+
+- `rebuild` 阶段：若 `fm.updated` 存在，写入 `updated_at`；否则使用文件 `mtime` 的 ISO 字符串。若两者皆不可得，使用当前 rebuild 时间的 ISO 字符串。
+- `recall --since` 阶段：TS 解析 `--since` 值 → 计算 threshold ISO → SQL `WHERE cards.updated_at >= ?`。`updated_at = NULL` 的卡片不匹配（rebuild 兜底已消除 null）。
+
+此契约保证：
+- 所有卡片都有 `updated_at`（消除 null）。
+- 手动编辑卡片（mtime 更新）能正确反映在 `--since` 过滤中。
+- `pmem update --confirm` 更新 frontmatter `updated` 字段的卡片，以声明时间为准。
+- 时间比较使用同一种字符串格式（ISO 8601），字典序可正确比较。
+
+### 5.2 Exit code 修正（含兼容性验收）
+
+**现状：**
+
+| 命令 | 当前行为 | 代码位置 |
+|------|---------|---------|
+| `pmem status` | 有 changes → exit 1 | `src/commands/status.ts:206` |
+| `pmem update --suggest` | 有 actionable suggestions → exit 1 | `src/commands/update.ts:699` |
+| `pmem distill --suggest` | 有 distillation suggestions → exit 1 | `src/commands/distill.ts:94` |
+
+**修改：** 三个命令统一为：有结果时 exit 0，仅在运行时错误（DB 打不开、卡片损坏等）时 exit 2。exit 1 不再作为 "workflow signal" 使用。
+
+**影响面评估（全量）：**
+
+| 文件 | 影响 | 处理 |
+|------|------|------|
+| `src/commands/status.ts:206` | `process.exit(1)` → `process.exit(0)` | 改一行 |
+| `src/commands/update.ts:699` | `process.exit(hasActionable ? 1 : 0)` → `process.exit(0)` | 改一行 |
+| `src/commands/distill.ts:94` | `process.exit(1)` → `process.exit(0)` | 改一行 |
+| `README.md:116,295` | 文档 "exits with code 1" | 更新为 exit 0 |
+| `AGENTS.md:37` | 文档引用 exit code | 更新 |
+| `docs/usage.md:131,199,316,333` | 多处 exit code 说明 | 更新 |
+| `docs/handover-v0.4.md:37,41,44,143,251-255,318` | 退出码协议、命令表 | 标记为历史，更新当前约定 |
+| `docs/handover-v0.6.md:81` | 设计规则 #7 | 更新 |
+| `docs/v0.4 pre-design.md:251,253,255,261,406` | 退出码约定表 | 标记为 v0.4 历史 |
+| `docs/v0.5 pre-design.md:104,106,212,286,300,304,405,428` | 退出码文档 | 标记为 v0.5 历史，README 已更新 |
+| `docs/v0.6 pre-design.md:190,382,398` | v0.6 exit code 设计 | 标注为已变更 |
+| `docs/v0.6.1 pre-design.md:98,202,206,406,438,451,499,523,545` | v0.6.1 exit code 设计 | 标注为已变更 |
+| `skills/pmem/SKILL.md:93,143,177` | Agent skill 引用 | 更新 |
+| `CLAUDE.md` | 项目级 agent 指令，exit code 表 | 更新 |
+| `CHANGELOG.md` | 已有记录，需追加 breaking change | 追加 v0.6.2 条目 |
+
+> **影响面计数：15 个文件（3 个代码文件 + 12 个文档/配置/技能文件）。**
+
+**兼容性验收清单（开工后执行）：**
+
+- [ ] 三个命令的 exit code 在 "有结果" 场景为 0
+- [ ] 三个命令的 exit code 在 "运行时错误" 场景为 2
+- [ ] `README.md` exit code 文档已更新
+- [ ] `docs/usage.md` exit code 文档已更新
+- [ ] `skills/pmem/SKILL.md` 已更新
+- [ ] `AGENTS.md` 已更新
+- [ ] `CLAUDE.md` exit code 表已更新
+- [ ] `CHANGELOG.md` 标注 breaking change
+- [ ] 所有 `docs/*pre-design*.md` 历史文档加注 "v0.6.2 已变更"
+- [ ] E2E 覆盖三个命令的 exit code 场景
+
+**风险与缓解：**
+
+- 依赖 exit 1 的现有脚本会行为变化 → CHANGELOG 显著标注 + README migration note
+- CI pipeline 中若有 `pmem update --suggest || echo "needs update"` 会失效 → 改为检查 JSON 输出中的 `summary.has_actionable`
+
+### 5.3 卡片模板生成 `pmem new`
+
+```bash
+pmem new decision "MLX-only Mac support decision"
+pmem new task "Implement voice input module"
+pmem new module "audio-pipeline"
+```
+
+**行为：**
+1. 根据卡片类型确定目标目录（`decisions/`、`tasks/`、`modules/` 等）
+2. 生成唯一 ID（基于标题 + 时间戳）
+3. 写入带完整 YAML frontmatter 的空卡片文件
+4. 当场校验必填字段完整性
+5. 输出文件路径和下一步建议
+
+**CLI 可触发的错误场景（E2E 验收用）：**
+
+| 场景 | 命令 | 预期结果 |
+|------|------|---------|
+| 正常生成 | `pmem new decision "My Decision"` | 写入文件，rebuild/verify 通过 |
+| 空 title | `pmem new task ""` | 拒绝写入，exit 2，提示 title 必填 |
+| 非法 type | `pmem new invalid_type "Test"` | 拒绝写入，exit 2，列出有效类型 |
+| 无参数 | `pmem new` | Commander 报 missing argument |
+
+内部 validator 可额外检查 frontmatter 缺字段等边界，但 E2E 仅测 CLI 可触发的错误。
+
+**生成的 frontmatter 模板（以 decision 为例）：**
+
+```yaml
+---
+id: decision.mlx_only_mac_20260523
+type: decision
+title: "MLX-only Mac support decision"
+status: draft
+tags: []
+created: "2026-05-23"
+source_files: []
+depends_on: []
+related_to: []
+---
+# MLX-only Mac support decision
+
+<!-- TODO: describe the decision, alternatives considered, and rationale -->
+```
+
+### 5.4 Frontmatter 创建时校验
+
+在 `pmem new` 写入文件前校验：
+- `type` 是有效类型（`decision|module|task|feature|risk|trace`）
+- `title` 非空且非空白字符串
+- 必填字段（id、type、title、status、created）完整性
+
+校验失败时当场报错，列出缺失/无效字段，不写入文件。这比当前"rebuild 时静默跳过无效卡片"的行为更友好。
+
+### 5.5 Git hook 集成
+
+```bash
+pmem integration install git-hooks
+```
+
+**行为：**
+1. 检测 `.git/hooks/` 是否存在
+2. 写入 `.git/hooks/pre-commit`（或追加到已有 hook）：
+
+```bash
+#!/bin/sh
+# pmem pre-commit hook — verify memory consistency before commit
+pmem verify --relaxed
+```
+
+3. `pmem integration verify` 检查 hook 是否已安装
+4. `pmem integration list` 增加 `git-hooks` 条目
+
+### 5.6 Session 健壮性排查
+
+调查 "No active pmem session found" 在已知 `session start` 已执行后仍然出现的根因。可能原因：
+
+- `session start` 写入 SQLite 后进程退出，下次 `session end` 在另一个进程中读取，WAL 未同步
+- 数据库连接关闭时机导致未提交
+- `session start` 检查到已有 active session 但用户在不知情的情况下多次 start
+
+排查策略：
+1. 复现：在 temp 目录模拟快速 start → end 周期
+2. 检查 WAL 模式下的写入可见性
+3. 若根因在 WAL，在 `session start` 后显式执行 checkpoint
+4. 若根因在其他，针对性修复
+
+---
+
+## 六、测试计划
+
+### P0 测试（已通过 ✅）
+
+| 测试项 | 类型 | 状态 |
+|--------|------|------|
+| `acquireLock` stale lock 自动清理 | E2E | ✅ |
+| `acquireLock` active lock 超时保留 | E2E | ✅ |
+| `verify --fix-locks` 清理 stale lock | E2E | ✅ |
+| `verify --fix-locks` 不删除 active lock | E2E | ✅ |
+| `doctor` lock 三种状态输出 | E2E | ✅ |
+| `verify` 检测 oversized card | E2E | ✅ |
+| `verify --relaxed` 翻倍限制 | E2E | ✅ |
+| manifest `max_tokens` 自定义生效 | E2E | ✅ |
+| `rename` 默认 preview 不写入 | E2E | ✅ |
+| `rename --write` 写入 + rebuild + verify | E2E | ✅ |
+| `rename` 后 frontmatter hash 不变 | E2E | ✅ |
+| `rename --find ""` reject + exit 2 | CLI | ✅ |
+| `update --confirm` 锁失败文案更新 | CLI | ✅ |
+
+### P1 测试（待执行）
+
+- 单元测试：rebuild `updated_at` 时间契约（`fm.updated` / mtime / rebuild time fallback）
+- E2E：`recall --since 7d` 只返回近期卡片
+- 单元测试：三个命令 exit code 在有结果时为 0
+- 单元测试：三个命令 exit code 在运行时错误时为 2
+- E2E：`pmem new` 各类型模板生成正确
+- E2E：`pmem new` 空 title / 非法 type / 无参数拒绝写入
+- E2E：`pmem integration install git-hooks` 写入 pre-commit hook
+- E2E：`pmem integration verify` 检测 git-hooks
+- E2E：session start → end 周期复现 + 修复验证
+
+---
+
+## 七、无 schema migration
+
+v0.6.2 不改变 manifest schema_version、不改变卡片 frontmatter 结构、不改变数据库表结构。
+
+变更仅涉及：
+- CLI 行为（exit code、新命令、新参数）
+- 运行时行为（lock 自动清理、verify --relaxed）
+- 默认值（card_policy.max_tokens）
+
+所有现有 `.pmem/` 目录在 v0.6.2 下无需迁移即可正常使用。
+
+---
+
+## 八、与已有推迟项的关系
+
+v0.6.1 pre-design 中推迟到 v0.6.2 的项：
+
+| 推迟项 | v0.6.2 处理 |
+|--------|------------|
+| `pmem dirty list` | 不进 v0.6.2 |
+| `pmem dirty resolve --auto` | 不进 v0.6.2 |
+| `pmem dirty prune --older-than 7d` | 不进 v0.6.2 |
+| 完整 dirty lifecycle | 不进 v0.6.2 |
+| `--current-session` / auto-cleanup | 不进 v0.6.2 |
+
+这些项继续推迟。v0.6.2 由用户反馈驱动，不主动扩展 dirty lifecycle。
+
+---
+
+## 九、P1 实现批次
+
+### 9.1 实现顺序
+
+| # | 任务 | 复杂度 | 依赖 |
+|---|------|--------|------|
+| 1 | `recall --since` + `rebuild` 时间契约落地 | 低 | 无 |
+| 2 | exit code 修正（3 个命令 + 15 个文件） | 中 | 无 |
+| 3 | `pmem new <type> "<title>"` + frontmatter 创建时校验 | 低 | 无 |
+| 4 | `pmem integration install git-hooks` | 低 | 无 |
+| 5 | session 健壮性排查 + 修复 | 中 | 需在 temp 目录复现 |
+
+P1 各任务相互独立，可并行实现，但打包为同一批次提交。
+
+### 9.2 P1 DoD
+
+- [ ] `npm test` 通过
+- [ ] `recall --since 7d` 正确过滤，`rebuild` 阶段 `updated_at` 无 null
+- [ ] `recall --since abc` / `recall --since 7x` 返回 exit 2 + 错误信息
+- [ ] `pmem status` / `update --suggest` / `distill --suggest` 有结果时 exit 0，错误时 exit 2
+- [ ] 15 个受影响文件已更新（3 代码 + 12 文档/配置/技能）
+- [ ] `CHANGELOG.md` 标注 exit code breaking change
+- [ ] `pmem new decision "test"` 生成有效卡片 → rebuild → verify 通过
+- [ ] `pmem new task ""` 拒绝写入 + exit 2
+- [ ] `pmem new invalid_type "test"` 拒绝写入 + exit 2
+- [ ] `pmem integration install git-hooks` 写入 `.git/hooks/pre-commit`
+- [ ] `pmem integration verify` 检测到 git-hooks
+- [ ] session 排查结论记录，若有修复则附带 E2E 验证
+- [ ] E2E 覆盖 recall --since、exit code、pmem new、git-hooks
+
+### 9.3 不与 P0 混包
+
+P1 作为独立批次，在 P0 已验收的代码基础上增量提交。P1 验收不重新检查 P0 项，除非 P1 修改触及 P0 代码路径。
+
+---
+
+## 十、发布验收
+
+### P0（已验收 ✅）
+
+- [x] `npm test` 通过（90/90）
+- [x] E2E 覆盖 stale lock 自动清理、active lock 超时、`verify --fix-locks`、`doctor` lock 输出
+- [x] E2E 覆盖 manifest token 上调、`verify --relaxed`
+- [x] E2E 覆盖 `rename` 默认 dry-run 不写入、`--write` 后 rebuild verify 通过、frontmatter hash 不因 rename 变化
+- [x] CTO 验收通过（2026-05-23）
+
+### P1（待实现）
+
+- [ ] 所有 P1 DoD 项通过
+- [ ] CI 通过（Node 18/20/22）
+- [ ] E2E 覆盖 recall --since、exit code、pmem new、git-hooks、session
+
+### 通用
+
+- [ ] CI 通过（Node 18/20/22）
+- [ ] CHANGELOG 记录 exit code breaking change
+- [ ] docs/project-roadmap.md 更新 v0.6.2 状态为"已发布"
+
+---
+
+## 十一、审批记录
+
+| 角色 | 决定 | 日期 |
+|------|------|------|
+| 提交人 | Claude Opus 4.6 | 2026-05-23 |
+| CTO | 有条件批准 P0 开工；P1 设计待补强 | 2026-05-23 |
+| CTO | P0 验收通过；批准 P1 作为独立批次进入实现，不与 P0 混包 | 2026-05-23 |
+
+### CTO 修正点（已在此文档中落实）
+
+1. **`pmem rename` 安全语义修正**（§4.3）：默认 dry-run，显式 `--write` 才写入。`--dry-run` flag 已移除。
+2. **`recall --since` 时间契约补全**（§5.1）：明确时间来源优先级 `frontmatter.updated > 文件 mtime > rebuild timestamp`，消除 `updated_at IS NULL` 漏洞。
+3. **exit code 兼容性验收单列**（§5.2）：全量影响面评估 15 个文件，兼容性验收清单 11 项。
+
+### P0 复验修正（已落实）
+
+- `update --confirm` 锁失败文案已改为可恢复指引（`update.ts:247`）
+- `rename --find ""` 已拒绝执行并返回 exit 2（`rename.ts:28`）
+- rename body 不再 `.trim()`：仅移除显式 trim 调用，`splitFrontmatter` 中的 `trimStart()` 记为已知非阻塞 P2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmem-ai",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Project Memory for AI Agents: a local CLI runtime for project context, recall, and memory updates",
   "main": "dist/index.js",
   "bin": {
@@ -19,7 +19,8 @@
     "test:e2e:v06-claude": "bash scripts/e2e-v06-claude-integration.sh",
     "test:e2e:v06-empty": "bash scripts/e2e-v06-empty-guidance.sh",
     "test:e2e:v06-nongit": "bash scripts/e2e-v06-non-git-ux.sh",
-    "test:e2e:v06-skills": "bash scripts/e2e-v06-skills.sh"
+    "test:e2e:v06-skills": "bash scripts/e2e-v06-skills.sh",
+    "test:e2e:v061-suggest": "bash scripts/e2e-v061-suggest.sh"
   },
   "keywords": [
     "agent",