@fonlan/dsh-gitmemo 0.1.5 → 0.3.0

package/README.md

@@ -3,33 +3,34 @@
 **English** | [**简体中文**](README.zh.md)
 
 **Git-backed long-term memory for DeepSeek Harness (dsh)** — a Cordis plugin mirroring
-[GitMemo](https://github.com/fonlan/gitmemo). The agent stores completed task outcomes as
-markdown entries in a local **`.mem`** Git repository and searches them before starting new
-work. Git is the only dependency, and no manual memory commands are ever needed.
+[GitMemo](https://github.com/fonlan/gitmemo). The root agent stores completed task outcomes as
+**immutable** markdown entries in a local **`.mem`** Git repository (a single `main` branch with
+structured commit messages) and searches them before starting new work. Git is the only
+dependency, and no manual memory commands are ever needed.
 
 ## Key Characteristics
 
 - **Extremely simple** — once installed, no manual memory commands in day-to-day tasks
-- **Fully automated** — the agent runs `init`, `search`, `read`, `write`, `delete` as part of its normal task flow
+- **Fully automated** — the root agent runs `search`, `read`, `write`, `delete`, `replace` as part of its normal task flow
 - **Local-only & offline** — memory lives in a local `.mem` Git repository; no cloud dependency
 - **Git-only** — no runtime dependency beyond the `git` CLI
-- **Token-efficient** — reuses prior conclusions via `mem_search` instead of re-injecting context
-- **Prevents context bloat** — search-first workflow; the skill caps reads at 5 relevant memories
-- **Auditable** — every memory action is a commit in `.mem`'s Git history
-- **Traceable** — each memory can be traced and replayed from commit history
-- **Branch-aligned** — the `.mem` branch follows the project's current branch on writes
+- **Token-efficient** — reuses prior conclusions via `mem_search`; subagents carry neither the workflow rules nor the tool schemas
+- **Immutable entries** — every write creates a new file; corrections use `mem_replace` (one commit deletes the old file and adds the new one), withdrawal uses `mem_delete`
+- **Structured search** — commit messages carry `GitMemo-*` trailers (keywords, digest, search-text projections); search is `git log --grep --fixed-strings` over commit messages only — entry bodies are never scanned
+- **Auditable** — every memory action is a commit in `.mem`'s Git history; replaced/deleted entries stay readable by hash
+- **Crash-safe** — write/delete/replace run under a cross-process lock with a journal written before entry mutation; migration uses a sibling swap journal so an interrupted directory exchange is recovered before automatic initialization
+- **Single-branch** — `.mem` permanently stays on `main`; the code branch/SHA is recorded as entry metadata only
 
 ## What the Plugin Provides
 
 | Piece | Description |
 | --- | --- |
-| `mem_init` | Initialize the `.mem` repository (all other tools auto-initialize) |
-| `mem_search` | Search memories: `keywords` (comma-separated), `skip` (pagination), `mode` (`and` / `or` / `auto` — AND first, OR fallback). Returns up to 20 hits as `hash\|title\|date` |
-| `mem_read` | Read one memory entry by commit hash (full markdown) |
-| `mem_write` | Store a task outcome: `title` + `content` (or `content_file` / `file`), optional inline `body` (commit body; engine API still supports `body_file`). Commits `.mem/entries/<timestamp>-<slug>.md` and aligns the `.mem` branch |
-| `mem_delete` | Delete a memory entry by commit hash (then redo and rewrite) |
-| Always-on rules section | The complete workflow rules (gitmemo's `agents-template.md` equivalent) are injected into **every** session's system prompt — no skill load needed |
-| Session-start injection | On every new **root** agent session, the N most recent memory titles (`hash\|title\|date`) are automatically injected into that session's system prompt, so prior-session context is visible before any tool call; subagents are skipped and the lookup never creates `.mem` |
+| `mem_search` | Search memories: `keywords` (array of 1–12, 中英文同义词), `skip` + `snapshot` (stable pagination). Returns up to 20 scored hits with `summary` / `keywords` / `matched_keywords` |
+| `mem_read` | Read one memory entry by create/replace commit hash (full markdown; historical hashes stay readable) |
+| `mem_write` | Store a task outcome: `title` + `summary` + `keywords` (2–12) + `content` (engine generates front matter), optional `related_branches` / `related_paths`. One ADD commit per immutable file |
+| `mem_delete` | Withdraw an obsolete conclusion (requires `commit_hash` + `reason`) |
+| `mem_replace` | Correct an outdated conclusion in ONE atomic commit (D old + A new) — never delete-then-write |
+| Scoped rules | The workflow rules + the five tools are registered into **root agents only** (`delegationDepth === 0`) at `agent/created`; subagents carry neither |
 
 ## Installation
 
@@ -48,7 +49,7 @@ dsh plugin --profile web add /path/to/dsh-gitmemo
 ```
 
 Then restart the dsh profile (e.g. restart the `dsh web` process). The plugin registers on the
-host plane, so every agent session in that profile sees the tools and the skill.
+host plane, so every new **root** agent session in that profile sees the tools and the rules.
 
 ### Configuration
 
@@ -58,80 +59,77 @@ The bundle patch ships with sensible defaults; override them in the profile's
 ```yaml
 - id: dsh-gitmemo
   config:
-    memDirName: .mem       # memory repo directory name at the project root
-    searchLimit: 20        # max hits per mem_search call
-    branchAlign: true      # .mem branch follows the project branch on write
-    recentContextLimit: 5  # recent memory titles injected into each new session's system prompt (0 disables)
+    searchLimit: 20        # max hits per mem_search call (page size)
+    lockTimeoutMs: 30000   # cross-process lock wait timeout
     projectRoot: null      # optional explicit project root (defaults to the session cwd)
 ```
 
-## Memory Location
+## Memory Location & Format
 
 The `.mem` repository lives at the **project root** of the calling session's workspace
-(`git rev-parse --show-toplevel`, falling back to the working directory). Entries are
-markdown files under `.mem/entries/`; every operation is a commit, so the whole memory is
-readable with plain `git`:
+(`git rev-parse --show-toplevel`, falling back to the working directory; an explicit
+`projectRoot` config wins). The repo layout:
+
+```text
+.mem/
+├── .git/
+├── .gitmemo-format        # schema version marker, e.g. "2"
+└── entries/               # one immutable file per active memory
+    └── <utc-ms>-<digest-prefix>-<slug>.md
+```
+
+- `.mem` is initialized on its own `main` branch; initialization writes `.mem/` and the lock
+  file path into the parent repo's `.git/info/exclude` (never into a version-controlled
+  `.gitignore`), and refuses to run when the parent repo already tracks `.mem` content.
+- Every write creates a brand-new file with an exclusive create (never overwrites), commits
+  one ADD commit with structured trailers, and records the code branch/SHA/related paths in
+  the entry front matter.
+
+The whole memory stays readable with plain `git`:
 
 ```bash
 git -C .mem log --oneline
 git -C .mem show <commit-hash>
 ```
 
-> Tip: add `.mem/` to your project's `.gitignore` so the memory repository never mixes into project commits.
-
-## Agent Workflow (always-on rules)
-
-1. **Before work — search.** Extract 3-5 keywords from the request → `mem_search`. If more
-   than 5 hits are relevant, read only the 5 most likely (`mem_read`). Paginate with `skip`
-   20, 40, … when nothing relevant appears.
-2. **User unsatisfied — delete and rewrite.** `mem_delete <hash>` → redo from feedback →
-   `mem_write` a corrected entry.
-3. **End-of-session checkpoint — the only write path.** When the conversation is ending, review
-   the whole session and `mem_write` every completed repo-related task that still lacks a memory
-   and whose outcome is **valuable/reusable** (or was explicitly asked to be remembered). Never
-   duplicate an already-written entry; if a stored outcome is outdated, `mem_delete` it first,
-   then write the corrected entry. Never write for pure Q&A, incomplete tasks, non-repo work, or
-   purely operational git actions. Write all pending memories before closing the conversation.
-
-## Entry Format
-
-```markdown
----
-date: 2026-02-19T15:10:10Z
-status: done
-repo_branch: main
-repo_commit: 9f3e1a2
-mem_branch: main
-related_paths: [src/auth/login.ts]
-tags: [auth, security]
----
-### Original User Request
-(verbatim)
-### AI Understanding
-- Goal: / Constraints: / Out of scope:
-### Final Outcome
-- Changes/outputs summary
-```
+## Agent Workflow (always-on rules, root agents)
+
+1. **Before work — search.** For repo-related tasks, extract 1–12 中英文关键词 → `mem_search`.
+   Pure chat and general Q&A need no search.
+2. **Preselect results.** Based on `title` / `summary` / `keywords` / `score` /
+   `matched_keywords`, `mem_read` at most 5 most relevant memories; paginate with `skip` +
+   the returned `snapshot`.
+3. **End-of-session checkpoint — the only write path.** When the conversation is ending,
+   `mem_write` every completed repo-related task that still lacks a memory and whose outcome is
+   **valuable/reusable** (or was explicitly asked to be remembered). Never duplicate an
+   already-written entry. Never write for pure Q&A, incomplete tasks, non-repo work, or purely
+   operational git actions.
+4. **User correction.** If a stored conclusion is outdated and a replacement exists →
+   `mem_replace` (never delete-then-write). If it is obsolete with no replacement →
+   `mem_delete` with a `reason`.
+5. **Subagent results.** Only the root agent decides whether a session-level memory is written.
 
 ## Development
 
 ```bash
 npm install
 npm run build    # tsc → lib/
-npm test         # build + engine/plugin unit tests (node:test)
+npm test         # build + engine/plugin/migration unit tests (node:test)
 ```
 
 ## Layout
 
 ```
 dsh-gitmemo/
-├── package.json          # npm package; dsh.bundle.patch wires the profile layer
+├── package.json          # npm package; dsh.bundle.patch wires the profile layer; bin: dsh-gitmemo
 ├── cordis.patch.yml      # composition layer: the dsh-gitmemo row
 ├── src/
-│   ├── index.ts          # Cordis plugin: mem_* tools + gitmemo skill + prompt section
-│   └── mem.ts            # core engine (port of gitmemo scripts/mem.sh)
+│   ├── index.ts          # Cordis plugin: root-agent-scoped mem_* tools + workflow section
+│   ├── mem.ts            # core engine (protocol, lock/journal, search, write/read/delete/replace)
+│   ├── migrate.ts        # legacy migration (dry-run/apply, backup refs, CAS swap)
+│   └── cli.ts            # `dsh-gitmemo migrate` CLI entry
 ├── lib/                  # built output (committed; used by file:/git installs)
-└── test/mem.test.mjs     # engine + plugin unit tests
+└── test/mem.test.mjs     # engine + plugin + migration unit tests
 ```
 
 ## License

package/README.zh.md

@@ -3,33 +3,33 @@
 [**English**](README.md) | **简体中文**
 
 **基于 Git 的 DeepSeek Harness (dsh) 长期记忆插件** —— 一个镜像
-[GitMemo](https://github.com/fonlan/gitmemo) 功能的 Cordis 插件。Agent 会把已完成任务的结论以
-markdown 条目存入项目根目录的本地 **`.mem`** Git 仓库，并在开始新任务前先搜索既往记忆。唯一依赖
-是 Git，日常使用完全无需手动记忆命令。
+[GitMemo](https://github.com/fonlan/gitmemo) 功能的 Cordis 插件。根 Agent 会把已完成任务的结论以
+**不可变** markdown 条目存入项目根目录的本地 **`.mem`** Git 仓库（单一 `main` 分支 + 结构化提交信息），
+并在开始新任务前先搜索既往记忆。唯一依赖是 Git，日常使用完全无需手动记忆命令。
 
 ## 核心特性
 
 - **极其简单** —— 安装后日常任务无需任何手动记忆命令
-- **全自动** —— Agent 在正常任务流程中自动执行 `init` / `search` / `read` / `write` / `delete`
+- **全自动** —— 根 Agent 在正常任务流程中自动执行 `search` / `read` / `write` / `delete` / `replace`
 - **纯本地、可离线** —— 记忆存于本地 `.mem` Git 仓库，无云端依赖
 - **仅依赖 Git** —— 除 `git` CLI 外无任何运行时依赖
-- **省 token** —— 通过 `mem_search` 复用既有结论，而非反复注入上下文
-- **防止上下文膨胀** —— 先搜索后工作的流程，技能规定最多只读 5 条最相关记忆
-- **可审计** —— 每次记忆操作都是 `.mem` Git 历史中的一次提交
-- **可追溯** —— 每条记忆都能从提交历史中回溯与重放
-- **分支对齐** —— 写入时 `.mem` 分支跟随项目当前分支
+- **省 token** —— 通过 `mem_search` 复用既有结论；子代理既不携带工作流规则也不携带工具 schema
+- **条目不可变** —— 每次写入都创建新文件；更正用 `mem_replace`（一个提交同时删除旧文件、新增新文件），作废用 `mem_delete`
+- **结构化搜索** —— commit message 携带 `GitMemo-*` trailers（keywords、digest、search-text 投影）；搜索只对 commit message 执行 `git log --grep --fixed-strings`，绝不扫描条目正文
+- **可审计** —— 每次记忆操作都是 `.mem` Git 历史中的一次提交；被替换/删除的条目仍可按哈希读取
+- **崩溃安全** —— write/delete/replace 在修改条目前先写事务 journal；迁移另用 sibling swap journal，目录交换中断后会在自动初始化前恢复
+- **单分支** —— `.mem` 永远停留在 `main`；代码分支/SHA 只作为条目元数据记录
 
 ## 插件提供的内容
 
 | 内容 | 说明 |
 | --- | --- |
-| `mem_init` | 初始化 `.mem` 仓库（其余工具都会自动初始化） |
-| `mem_search` | 搜索记忆：`keywords`（逗号分隔）、`skip`（分页）、`mode`（`and` / `or` / `auto`，auto 先 AND 后 OR 兜底）。每次最多返回 20 条 `hash\|title\|date` |
-| `mem_read` | 按提交哈希读取一条记忆的完整 markdown |
-| `mem_write` | 存储任务结论：`title` + `content`（或 `content_file` / `file`），可选内联 `body`（commit body；引擎 API 仍支持 `body_file`）。提交为 `.mem/entries/<时间戳>-<slug>.md` 并对齐 `.mem` 分支 |
-| `mem_delete` | 按提交哈希删除记忆条目（然后重做并重写） |
-| 常驻规则片段 | 完整工作流规则（相当于 gitmemo 的 `agents-template.md`）注入**每个**会话的系统提示词——无需加载技能即可生效 |
-| 会话开始注入 | 每个新**根** Agent 会话开始时，自动把最近 N 条记忆标题（`hash\|title\|date`）注入该系统提示词，跨会话上下文在调用任何工具前即可见；子代理被跳过，且该查询只读、绝不创建 `.mem` |
+| `mem_search` | 搜索记忆：`keywords`（1–12 个关键词数组，建议中英文同义词）、`skip` + `snapshot`（稳定分页）。每次最多返回 20 条带 `summary` / `keywords` / `matched_keywords` 的评分结果 |
+| `mem_read` | 按创建/替换提交哈希读取一条记忆的完整 markdown（历史哈希仍可读） |
+| `mem_write` | 存储任务结论：`title` + `summary` + `keywords`（2–12）+ `content`（front matter 由引擎生成），可选 `related_branches` / `related_paths`。每个不可变文件对应一个 ADD 提交 |
+| `mem_delete` | 作废无替代结论（需要 `commit_hash` + `reason`） |
+| `mem_replace` | 一个原子提交内更正旧结论（D 旧文件 + A 新文件）—— 禁止先删后写 |
+| 作用域规则 | 工作流规则与五个工具只在 `agent/created` 时注册进**根 Agent**（`delegationDepth === 0`）；子代理两者皆无 |
 
 ## 安装
 
@@ -47,8 +47,8 @@ dsh plugin --profile web add @fonlan/dsh-gitmemo
 dsh plugin --profile web add /path/to/dsh-gitmemo
 ```
 
-然后重启对应的 dsh profile（例如重启 `dsh web` 进程）。插件注册在宿主平面，该 profile 下所有
-Agent 会话都能看到这些工具与技能。
+然后重启对应的 dsh profile（例如重启 `dsh web` 进程）。插件注册在宿主平面，该 profile 下每个新
+**根** Agent 会话都能看到这些工具与规则。
 
 ### 配置
 
@@ -57,75 +57,69 @@ bundle patch 自带合理默认值，可在 profile 的 `cordis.patch.yml` 中
 ```yaml
 - id: dsh-gitmemo
   config:
-    memDirName: .mem       # 项目根目录下记忆仓库的目录名
-    searchLimit: 20        # 每次 mem_search 返回的最大条数
-    branchAlign: true      # 写入时 .mem 分支跟随项目分支
-    recentContextLimit: 5  # 注入每个新会话系统提示词的最近记忆条数（0 表示关闭）
+    searchLimit: 20        # 每次 mem_search 返回的最大条数（每页大小）
+    lockTimeoutMs: 30000   # 跨进程锁等待超时
     projectRoot: null      # 可选：显式项目根目录（默认取会话工作目录）
 ```
 
-## 记忆存放位置
+## 记忆存放位置与格式
 
 `.mem` 仓库位于调用会话工作区的**项目根目录**（`git rev-parse --show-toplevel`，找不到时退回
-工作目录）。条目是 `.mem/entries/` 下的 markdown 文件；每次操作都是一次提交，整个记忆可以用
-普通 `git` 命令查看：
+工作目录；显式配置 `projectRoot` 优先）。仓库结构：
+
+```text
+.mem/
+├── .git/
+├── .gitmemo-format        # schema 版本标记，如 "2"
+└── entries/               # 每个活跃记忆一个不可变文件
+    └── <utc-ms>-<digest-prefix>-<slug>.md
+```
+
+- `.mem` 初始化在自己的 `main` 分支上；初始化时把 `.mem/` 与锁文件路径写入父仓库的
+  `.git/info/exclude`（绝不写入受版本控制的 `.gitignore`），且当父仓库已跟踪 `.mem` 内容时拒绝初始化。
+- 每次写入都用独占创建生成全新文件（绝不覆盖），以带结构化 trailers 的 ADD 提交落库，并把代码
+  分支/SHA/相关路径记录在条目 front matter 中。
+
+整个记忆可以用普通 `git` 命令查看：
 
 ```bash
 git -C .mem log --oneline
 git -C .mem show <commit-hash>
 ```
 
-> 提示：建议把 `.mem/` 加入项目的 `.gitignore`，避免记忆仓库混入项目提交。
-
-## Agent 工作流（常驻规则）
-
-1. **开工前 —— 搜索。** 从请求中提取 3-5 个关键词 → `mem_search`。若相关结果超过 5 条，只
-   `mem_read` 最可能相关的 5 条。无相关结果时用 `skip` 20、40… 翻页。
-2. **用户不满意 —— 删除重写。** `mem_delete <hash>` → 按反馈重做 → `mem_write` 更正后的条目。
-3. **会话结束检查点 —— 唯一的写入路径。** 对话即将结束时，回顾整个会话，用 `mem_write` 写入
-   **每一条**已完成、与仓库相关、且结论**有价值/可复用**（或用户明确要求记住）但还没有记忆的任务。
-   绝不重复写已存在的条目；若已存结论已过时，先 `mem_delete` 再写更正条目。纯问答、未完成任务、
-   与仓库无关的工作、纯操作性的 git 动作一律不写。关闭会话前写完所有待写记忆。
-
-## 条目格式
-
-```markdown
----
-date: 2026-02-19T15:10:10Z
-status: done
-repo_branch: main
-repo_commit: 9f3e1a2
-mem_branch: main
-related_paths: [src/auth/login.ts]
-tags: [auth, security]
----
-### Original User Request
-(verbatim)
-### AI Understanding
-- Goal: / Constraints: / Out of scope:
-### Final Outcome
-- Changes/outputs summary
-```
+## Agent 工作流（常驻规则，仅根 Agent）
+
+1. **开工前 —— 搜索。** 仓库相关任务开始前提取 1–12 个中英文关键词 → `mem_search`。纯闲聊和通用问答无需搜索。
+2. **结果预筛。** 根据 `title` / `summary` / `keywords` / `score` / `matched_keywords` 最多
+   `mem_read` 5 条最相关记忆；用 `skip` + 返回的 `snapshot` 翻页。
+3. **会话结束检查点 —— 唯一的写入路径。** 对话即将结束时，`mem_write` **每一条**已完成、与仓库
+   相关、且结论**有价值/可复用**（或用户明确要求记住）但还没有记忆的任务。绝不重复写已存在的条目。
+   纯问答、未完成任务、与仓库无关的工作、纯操作性的 git 动作一律不写。
+4. **用户更正。** 已存结论过时且有替代结论 → `mem_replace`（禁止先 delete 再 write）；结论作废且无
+   替代 → 带 `reason` 的 `mem_delete`。
+5. **子代理结果。** 是否形成一条会话级记忆，由根 Agent 汇总后决定。
 
 ## 开发
 
 ```bash
 npm install
 npm run build    # tsc → lib/
-npm test         # 构建 + 引擎/插件单元测试（node:test）
+npm test         # 构建 + 引擎/插件/迁移单元测试（node:test）
 ```
 
 ## 目录结构
 
 ```
 dsh-gitmemo/
-├── package.json          # npm 包；dsh.bundle.patch 接入 profile 层
+├── package.json          # npm 包；dsh.bundle.patch 接入 profile 层；bin: dsh-gitmemo
 ├── cordis.patch.yml      # 组合层：dsh-gitmemo 行
 ├── src/
-│   ├── index.ts          # Cordis 插件：mem_* 工具 + gitmemo 技能 + 提示词片段
-│   └── mem.ts            # 核心引擎（gitmemo scripts/mem.sh 的移植）
+│   ├── index.ts          # Cordis 插件：仅根 Agent 的 mem_* 工具 + 工作流片段
+│   ├── mem.ts            # 核心引擎（协议、锁/journal、搜索、write/read/delete/replace）
+│   ├── migrate.ts        # 旧格式迁移（dry-run/apply、backup refs、CAS 交换）
+│   └── cli.ts            # `dsh-gitmemo migrate` CLI 入口
 ├── lib/                  # 构建产物（已提交，供 file:/git 安装使用）
-└── test/mem.test.mjs     # 引擎 + 插件单元测试
+└── test/mem.test.mjs     # 引擎 + 插件 + 迁移单元测试
 ```
 
 ## License

package/cordis.patch.yml

@@ -3,9 +3,15 @@
 # Installing this package into a profile (`dsh plugin --profile <name> add @fonlan/dsh-gitmemo`)
 # appends it to `dsh.profile.bundles`; this patch is then applied as that
 # bundle's layer. The row below loads the package's main entry as a host-plane
-# plugin: it registers the `mem_init` / `mem_search` / `mem_read` /
-# `mem_write` / `mem_delete` tools on the shared tool registry, a runtime
-# `gitmemo` skill, and a system-prompt section pointing at the memory workflow.
+# plugin: at every ROOT-agent creation it scopes the
+# `mem_search` / `mem_read` / `mem_write` / `mem_delete` / `mem_replace`
+# tools plus the memory workflow system-prompt section into that agent
+# (subagents get neither). No session-start scanning, no Git I/O at
+# registration time.
+#
+# `memDirName` / `branchAlign` / `recentContextLimit` are deprecated and kept
+# only for one compatibility version (they are parsed but have no effect;
+# `.mem` is fixed at <projectRoot>/.mem and always stays on main).
 - insert:
     - id: dsh-gitmemo
       # Node-resolvable package name — must stay in sync with package.json
@@ -15,3 +21,4 @@
       config:
         memDirName: .mem
         searchLimit: 20
+        lockTimeoutMs: 30000

package/lib/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * dsh-gitmemo CLI — explicit legacy migration (plan 10).
+ *
+ *   dsh-gitmemo migrate --project-root <path> [--dry-run|--apply]
+ *     [--source <legacy-mem-dir>] [--out <baseline-file>] [--baseline <file>]
+ *
+ * Dry-run scans the legacy `.mem` repo without touching any ref/index/work
+ * tree state and prints the plan (dedupe, conflicts, estimated commits).
+ * `--apply` re-verifies the baseline refs, then migrates inside the
+ * cross-process lock; the original `.mem` is only replaced after the new
+ * canonical main is fully built and verified.
+ *
+ * @module dsh-gitmemo/cli
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { GitMemoError } from "./mem.js";
+import { migrateApply, migrateDryRun } from "./migrate.js";
+function usage() {
+    return [
+        "usage: dsh-gitmemo migrate --project-root <path> [--dry-run|--apply]",
+        "       [--source <legacy-mem-dir>] [--out <baseline-file>] [--baseline <file>]",
+        "",
+        "  --project-root <path>  code project root (the .mem sibling lives here)",
+        "  --dry-run              scan the legacy repo and print the migration plan (default)",
+        "  --apply                execute migration (uses --baseline, or performs a fresh dry-run first)",
+        "  --source <dir>         legacy memory dir (default <projectRoot>/.mem)",
+        "  --out <file>           write the dry-run baseline JSON to a file",
+        "  --baseline <file>      baseline JSON produced by a previous --dry-run",
+        "  --help, -h             show this help"
+    ].join("\n");
+}
+function parseArgs(argv) {
+    const args = { projectRoot: "", action: "dry-run" };
+    // optional subcommand token: `dsh-gitmemo migrate --project-root ...`
+    if (argv[0] === "migrate")
+        argv = argv.slice(1);
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--project-root":
+            case "--projectRoot": {
+                const value = argv[i + 1];
+                if (value === undefined)
+                    throw new GitMemoError("gitmemo: --project-root requires a path");
+                args.projectRoot = value;
+                i += 1;
+                break;
+            }
+            case "--dry-run":
+                args.action = "dry-run";
+                break;
+            case "--apply":
+                args.action = "apply";
+                break;
+            case "--source":
+            case "--sourceDir": {
+                const value = argv[i + 1];
+                if (value === undefined)
+                    throw new GitMemoError("gitmemo: --source requires a path");
+                args.source = value;
+                i += 1;
+                break;
+            }
+            case "--out": {
+                const value = argv[i + 1];
+                if (value === undefined)
+                    throw new GitMemoError("gitmemo: --out requires a file path");
+                args.out = value;
+                i += 1;
+                break;
+            }
+            case "--baseline": {
+                const value = argv[i + 1];
+                if (value === undefined)
+                    throw new GitMemoError("gitmemo: --baseline requires a file path");
+                args.baseline = value;
+                i += 1;
+                break;
+            }
+            case "--help":
+            case "-h":
+                console.log(usage());
+                process.exit(0);
+                break;
+            default:
+                throw new GitMemoError("gitmemo: unknown argument: " + arg + "\n" + usage());
+        }
+    }
+    if (args.projectRoot.length === 0) {
+        throw new GitMemoError("gitmemo: --project-root is required\n" + usage());
+    }
+    return args;
+}
+function printDryRun(root, report) {
+    if (report.alreadyNewFormat === true) {
+        console.log(`gitmemo: ${report.baseline.memDir} is already in new format — nothing to migrate.`);
+        return;
+    }
+    const lines = [
+        `gitmemo migration dry-run for ${root}`,
+        `  source:                ${report.baseline.memDir}`,
+        `  legacy branches:       ${report.branches.join(", ") || "(none)"}`,
+        `  active legacy entries: ${report.oldEntryCount}`,
+        `  unique entries:        ${report.uniqueEntryCount}`,
+        `  conflicts:             ${report.conflictCount}`,
+        `  estimated main commits: ${report.estimatedMainCommits} (1 init + ${report.uniqueEntryCount} entries)`
+    ];
+    if (report.conflictCount > 0) {
+        lines.push("  conflict manifest:");
+        for (const conflict of report.baseline.conflicts) {
+            const variants = conflict.variants.map((v) => `${v.branch}@${v.hash.slice(0, 12)}`).join(", ");
+            lines.push(`    ${conflict.path}: [${variants}]`);
+        }
+        lines.push("  → resolve the conflicts, then re-run --dry-run to produce a clean baseline.");
+    }
+    for (const warning of report.warnings)
+        lines.push("  warning: " + warning);
+    lines.push("Next: review and run `dsh-gitmemo migrate --project-root <path> --apply` (or pass a saved --baseline file).");
+    console.log(lines.join("\n"));
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const root = resolve(args.projectRoot);
+    if (args.action === "dry-run") {
+        const report = await migrateDryRun(root, { source: args.source });
+        printDryRun(root, report);
+        if (args.out !== undefined) {
+            await writeFile(args.out, JSON.stringify(report.baseline, null, 2) + "\n", "utf8");
+            console.log(`baseline written to ${args.out}`);
+        }
+        return;
+    }
+    let baseline;
+    if (args.baseline !== undefined) {
+        try {
+            baseline = JSON.parse(await readFile(args.baseline, "utf8"));
+        }
+        catch (error) {
+            throw new GitMemoError("gitmemo: cannot read baseline file " + args.baseline + ": " + String(error));
+        }
+    }
+    else {
+        const report = await migrateDryRun(root, { source: args.source });
+        if (report.alreadyNewFormat === true) {
+            console.log(`gitmemo: ${report.baseline.memDir} is already in new format — nothing to migrate.`);
+            return;
+        }
+        if (report.conflictCount > 0) {
+            printDryRun(root, report);
+            throw new GitMemoError("gitmemo: migration has conflicts — resolve them before --apply");
+        }
+        baseline = report.baseline;
+    }
+    const report = await migrateApply(root, baseline, { source: args.source });
+    if (report.alreadyMigrated === true) {
+        console.log(`gitmemo: ${baseline.memDir} is already in new format — nothing to migrate.`);
+        return;
+    }
+    console.log([
+        `gitmemo migration applied for ${root}`,
+        `  entries reimported: ${report.entries}`,
+        `  old branches backed up: ${report.oldBranches.join(", ")}`,
+        `  backup refs: ${report.backupRefPrefix}<branch> (kept permanently; old hashes stay readable)`,
+        `  new main: ${report.newMain}`
+    ].join("\n"));
+}
+main().catch((error) => {
+    const message = error instanceof GitMemoError ? error.message : String(error);
+    console.error("gitmemo: " + message);
+    process.exit(1);
+});