dev-memory-cli 0.22.2 → 0.23.0

package/lib/maintenance/archive.md

@@ -0,0 +1,84 @@
+# 分支记忆归档维护流程
+
+目标是把已完成分支中真正跨分支复用的知识提炼到 repo 共享层，然后归档该分支的记忆目录。归档是破坏性显式动作，必须由用户确认。
+
+## 硬规则
+
+- 始终只处理提示中指定的 repo + branch。
+- 所有命令都使用提示中给出的 CLI 路径，并显式传 `--repo`、必要时传 `--branch`。
+- 禁止跳过 dry-run 直接 apply。
+- 当前分支存在未提交改动、领先默认基线且尚未 merge，或仍在开发时，不得擅自归档；先向用户说明并确认。
+- pending-promotion 只是候选，不是必选。业务专用事实不得上提到 repo 共享层。
+- 上提决策必须保留 Why 与影响范围，并改写成脱离当前分支名称仍可理解的最终事实。
+
+## 第一阶段：pre-flight
+
+运行：
+
+```bash
+<CLI> graduate dry-run --repo <REPO> [--branch <BRANCH>]
+```
+
+检查并向用户报告：
+
+- `git_status.ahead`
+- `git_status.uncommitted`
+- 默认基线与当前分支
+- `archive_destination`
+- 主审核面 `primary_sources.pending-promotion.md`
+- 主审核面 `primary_sources.decisions.md`
+- 其他 `cross_check_sources` 中可能遗漏的跨分支经验
+
+若 pre-flight 暴露未 merge 或未提交状态，停止在确认点，不要继续生成 apply。
+
+## 第二阶段：生成 harvest 草案
+
+只提炼真正跨分支稳定成立的内容，生成：
+
+```json
+{
+  "repo_overview": [
+    {"section": "长期目标与边界", "body": "...", "mode": "append"}
+  ],
+  "repo_decisions": [
+    {"section": "跨分支通用决策", "body": "...", "mode": "append"}
+  ],
+  "repo_glossary": [
+    {"section": "长期有效背景", "body": "...", "mode": "append"},
+    {"section": "共享入口", "body": "...", "mode": "append"}
+  ],
+  "notes": "从目标分支提炼",
+  "archive": true
+}
+```
+
+提炼时：
+
+- 去掉当前需求名、临时人员分工、一次性状态和提交流水。
+- 保留通用约束、反直觉风险、长期资料入口和可复用流程。
+- 对照现有 repo 共享记忆去重；旧共享结论失效时应改成最终口径，不能制造两条冲突规则。
+- 默认 `mode=append`，除非已经确认需要更新已有 section。
+
+把 harvest 草案完整展示给用户，包括“会上提什么”和“只归档、不做上提什么”。获得明确确认之前禁止 apply。
+
+## 第三阶段：apply
+
+用户确认草案与归档目标后运行：
+
+```bash
+<CLI> graduate apply --repo <REPO> [--branch <BRANCH>] --harvest-file <HARVEST>
+```
+
+apply 会串行写入 repo 共享层，生成 `archive_summary.md`，并把分支目录移动到 `branches/_archived/<branch>__<date>/`，同时更新 `_archived/INDEX.md`。
+
+## 第四阶段：复核
+
+完成后必须：
+
+1. 读取 `archive_summary.md`。
+2. 运行 `<CLI> graduate index --repo <REPO>` 确认归档索引存在。
+3. 检查原 branch_dir 已移动、archive destination 存在。
+4. 汇总实际上提条目、归档路径和任何跳过项。
+
+如果 apply 报 branch 不存在、schema 漂移或并发归档冲突，停止并报告真实错误；不得强行移动目录或手写 INDEX 绕过 CLI。
+

package/lib/maintenance/tidy.md

@@ -0,0 +1,103 @@
+# 记忆整理维护流程
+
+目标是把未分类内容归位，并校准已经结构化但陈旧、重复、错误或残留模板的记忆。整理是显式维护任务，不在普通开发会话中自动触发。
+
+## 硬规则
+
+- 始终只处理提示中指定的单个 repo + branch。
+- 所有命令都使用提示中给出的 CLI 路径，并显式传 `--repo`、必要时传 `--branch`。
+- 未分类内容可以在用户确认分类后 merge；结构化内容的删除和改写必须先生成 HTML review，由用户审核并导出 plan，禁止直接 apply。
+- 不复制 PRD、聊天流水或 Git 历史；只保留下次开发仍有价值的决策、风险、术语、约束、入口与文件导航。
+- `progress.md` 的 `AUTO-GENERATED` 块不得删除或改写。
+
+## 第一阶段：处理 unsorted
+
+先运行：
+
+```bash
+<CLI> setup init --repo <REPO> [--branch <BRANCH>]
+```
+
+如果 `unsorted_entries` 非空：
+
+1. 把相关条目聚合后给出高置信度分类建议。
+2. 可选 kind：`decision`、`risk`、`glossary`、`source`、`shared-decision`、`shared-context`、`shared-source`、`skip`。
+3. 让用户确认或修正分类；未确认前不要 merge。
+4. 生成 `classifications` plan，并运行 `setup merge-unsorted --plan-file ...`。
+
+如果 unsorted 为空，不需要为了修改 `setup_completed` 制造额外步骤；继续结构化整理即可。
+
+## 第二阶段：扫描结构化记忆
+
+运行：
+
+```bash
+<CLI> tidy prepare --repo <REPO> [--branch <BRANCH>] --scope <SCOPE>
+```
+
+`SCOPE` 使用启动提示中的 `branch` 或 `branch+repo`。第一次 prepare 后优先读取输出中的 `annotated_md`，不要只看 stdout 的扁平 entries。它保留了：
+
+- entry id
+- block 边界
+- section 结构
+- Why/How 等 orphan paragraph
+- STALE / ORPHAN hints
+
+## 第三阶段：生成事项级 proposals
+
+把相关条目聚合成约 3～8 个 proposal，每个 proposal 必须包含 `id`、`priority`、`title`、`reason`、`actions`。优先使用粗粒度动作：
+
+1. `reset-file`
+2. `delete-section`
+3. `delete-block`
+4. `delete-entries`
+5. `edit-entries`
+
+不要把每个 entry 单独做成 proposal。同一原因、同一结果的动作应合并。删除 block 时尽量附带 prepare 输出的 `expected_content_hash`，防止用户中途修改文件后误删。
+
+priority 口径：
+
+- `P0`：继续保留会误导下一次开发
+- `P1`：强烈建议清理
+- `P2`：建议清理
+- `P3`：可选
+- `P4`：可有可无
+
+把 proposals 写入临时 JSON，再次运行：
+
+```bash
+<CLI> tidy prepare --repo <REPO> [--branch <BRANCH>] --scope <SCOPE> --proposals-file <FILE>
+```
+
+## 第四阶段：人工审核门禁
+
+把 `review_html` / `open_url` 告诉用户，引导用户逐个选择：
+
+- accept：按原方案执行
+- reject：保持不动
+- custom：给出新的处理意见
+
+用户审核后从 HTML 导出 plan.json，并把路径交回本会话。没有用户导出的 plan 文件，禁止调用 `tidy apply`。
+
+## 第五阶段：apply 与复核
+
+用户明确提供已审核 plan 后运行：
+
+```bash
+<CLI> tidy apply --repo <REPO> [--branch <BRANCH>] --plan-file <PLAN>
+```
+
+apply 会先备份，再按 reset → section → block → entry 的顺序执行。完成后必须读取生成的 `summary_*.md`，核对 accepted/rejected/custom、实际 rewritten/deleted 和 invalid actions。
+
+custom proposal 不会自动 apply。根据反馈决定是直接精确改写、解释后再确认、保持不动，还是重新生成 proposals；不要机械重复整轮 prepare。
+
+## 完成输出
+
+最终向用户说明：
+
+- unsorted 分类合并了多少条
+- HTML 审核了多少个 proposal
+- 实际改写、删除、重置的数量
+- 备份和 summary 路径
+- 因漂移校验而跳过的动作
+

package/lib/ui-app.html

@@ -743,7 +743,7 @@ function renderScan() {
       el("td", { class: "num" }, run.session_count),
       el("td", { class: "num" }, formatBytes(run.new_bytes)),
       el("td", { class: "num" }, usage == null ? "未上报" : Number(usage).toLocaleString()),
-      el("td", null, run.done_count + " 完成 · " + run.failed_count + " 失败 · " + run.skipped_count + " 跳过")
+      el("td", null, run.status ? run.status : (run.done_count + " 完成 · " + run.failed_count + " 失败 · " + run.skipped_count + " 跳过"))
     ));
   });
   runTable.appendChild(runBody);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-memory-cli",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "CLI for dev-memory hooks and repo-local setup (formerly @xluos/dev-assets-cli)",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
     "hooks/*.json",
     "hooks/README.md",
     "lib/*.py",
+    "lib/maintenance/*.md",
     "lib/ui-server.js",
     "lib/ui-app.html",
     "lib/assets/*",

package/scripts/hooks/_common.py

@@ -490,13 +490,12 @@ def _extract_sections(paths, keys, *, repo_newest_first=False):
 
 def _build_context_from_assets(assets, *, full=True, heading=None, brief_profile="standard"):
     if not assets["branch_dir"].exists():
-        # v2: capture lazy-inits on first write, so branch_dir typically
-        # exists after any real interaction. Missing here just means no
-        # write has happened yet — no need to push setup.
+        # Memory is opt-in. A missing branch directory stays silent in
+        # workspace briefs; the primary repo gets a concise init hint.
         if heading is None:
             return (
                 "当前仓库+分支还没有 dev-memory 记忆。"
-                "下一次 `dev-memory-capture` 写入时会自动 lazy init；现有结论若值得记一笔，直接走 capture。"
+                "需要启用时运行 `dev-memory-cli init`；之后由定期 session-scan 沉淀会话语义。"
             )
         return None
 
@@ -617,7 +616,7 @@ def _build_context_from_assets(assets, *, full=True, heading=None, brief_profile
                 "",
                 f"归档分支查询：`grep -r 'KEYWORD' {archive_dir}/` （体量大时派 Task 子 agent）",
             ])
-        footer_lines.extend(["", "新决策 / 进展 / 阻塞 → `dev-memory-capture` 写入。"])
+        footer_lines.extend(["", "新增会话语义由定期 session-scan 沉淀；主动查旧记忆使用 `dev-memory-read`。"])
         parts.append("\n".join(footer_lines))
 
     return "\n\n".join(parts)

package/suite-manifest.json

@@ -1,13 +1,13 @@
 {
   "suite_name": "dev-memory-skill-suite",
   "skills": [
-    "dev-memory-read",
+    "dev-memory-read"
+  ],
+  "legacy_skills": [
     "dev-memory-setup",
     "dev-memory-capture",
     "dev-memory-graduate",
-    "dev-memory-tidy"
-  ],
-  "legacy_skills": [
+    "dev-memory-tidy",
     "branch-context",
     "branch-context-setup",
     "dev-asset-setup",