Add repo-memory CLI test docs

2026-03-20 15:42:35 +08:00
parent e32c81db12
commit a6ffc376e3
43 changed files with 1583 additions and 17 deletions
@@ -0,0 +1,11 @@
+# Repo Memory `verify` Test Plan Index
+
+## Case Files
+
+| Case Slug | File | Coverage Note |
+| --- | --- | --- |
+| `verify-downgrades-changed-file-dependency` | [verify-downgrades-changed-file-dependency.md](./verify-downgrades-changed-file-dependency.md) | downgrades a confirmed entry to `needs_review` when a tracked file changed |
+| `verify-marks-missing-hard-dependency-stale` | [verify-marks-missing-hard-dependency-stale.md](./verify-marks-missing-hard-dependency-stale.md) | marks a confirmed entry `stale` when a hard dependency disappears |
+| `verify-prints-no-repos-when-empty` | [verify-prints-no-repos-when-empty.md](./verify-prints-no-repos-when-empty.md) | prints `no repos` when the initialized DB has no tracked repositories |
+| `verify-skips-explicit-repo-without-git-head` | [verify-skips-explicit-repo-without-git-head.md](./verify-skips-explicit-repo-without-git-head.md) | prints a skip line when the explicit repo is not a Git repo or has no HEAD |
+| `verify-downgrades-entry-missing-verified-on-commit` | [verify-downgrades-entry-missing-verified-on-commit.md](./verify-downgrades-entry-missing-verified-on-commit.md) | downgrades an entry to `needs_review` once the repo becomes verifiable but the entry lacks `verified_on_commit` |
@@ -0,0 +1,36 @@
+# Case: `verify-downgrades-changed-file-dependency`
+
+## 用例意义
+
+验证 `verify` 在硬依赖文件内容发生变更时，会把 `confirmed` entry 降级为 `needs_review`。
+
+## 前置条件
+
+- 空数据库已完成 `init`
+- `TMPDIR/repo` 是一个已提交初始 commit 的 Git 仓库
+- 已执行：
+
+```bash
+repo-memory add --db TMPDIR/repo-memory.db --repo TMPDIR/repo --kind term --key AITask --summary "Plan 内嵌任务结构" --status confirmed --dep file:TMPDIR/repo/foo.txt:hard
+```
+
+- 在执行 `verify` 前，`TMPDIR/repo/foo.txt` 已被修改但尚未重新验证
+
+## 输入
+
+```bash
+repo-memory verify --db TMPDIR/repo-memory.db --repo TMPDIR/repo
+repo-memory list --db TMPDIR/repo-memory.db --repo repo --status needs_review
+repo-memory events --db TMPDIR/repo-memory.db --id 1
+```
+
+## 预期输出
+
+- `verify` 输出包含 `verified 1 entries, 1 downgraded, 0 stale`
+- `list` 输出包含 `term:AITask [needs_review]`
+- `events` 输出包含 `downgraded (confirmed -> needs_review)`
+
+## 断言结论
+
+- 文件变更不会直接删除知识，而是先降级为 `needs_review`
+- `verify` 会同时更新当前状态与历史事件
@@ -0,0 +1,37 @@
+# Case: `verify-downgrades-entry-missing-verified-on-commit`
+
+## 用例意义
+
+验证 entry 一旦缺少 `verified_on_commit`，在 repo 变得可验证后会被 `verify` 降级到 `needs_review`。
+
+## 前置条件
+
+- `TMPDIR/repo` 目录最开始不是 Git repo，但包含证据文件 `foo.txt`
+- 已执行：
+
+```bash
+repo-memory add --db TMPDIR/repo-memory.db --repo TMPDIR/repo --kind term --key AITask --summary "Recorded before git init" --status confirmed --dep file:TMPDIR/repo/foo.txt:hard
+```
+
+- 之后才把 `TMPDIR/repo` 初始化为 Git repo，并完成第一次 commit
+
+## 输入
+
+```bash
+repo-memory verify --db TMPDIR/repo-memory.db --repo TMPDIR/repo
+repo-memory list --db TMPDIR/repo-memory.db --repo repo --status needs_review
+repo-memory events --db TMPDIR/repo-memory.db --id 1
+```
+
+## 预期输出
+
+- `verify` 退出码为 `0`
+- `verify` 输出包含 `verified 1 entries, 1 downgraded, 0 stale`
+- `list` 输出包含 `term:AITask [needs_review]`
+- `events` 输出包含 `downgraded (confirmed -> needs_review)`
+- `events` 输出包含原因 `missing verified_on_commit`
+
+## 断言结论
+
+- 只要 entry 缺少 `verified_on_commit`，即使依赖文件当前存在，也不能继续保持 `confirmed`
+- 这个边界主要出现在“先写 repo-memory，后补 Git 历史”的仓库演进阶段
@@ -0,0 +1,36 @@
+# Case: `verify-marks-missing-hard-dependency-stale`
+
+## 用例意义
+
+验证 `verify` 在硬依赖文件已经不存在时，会把 entry 标记为 `stale`。
+
+## 前置条件
+
+- 空数据库已完成 `init`
+- `TMPDIR/repo` 是一个已提交初始 commit 的 Git 仓库
+- 已执行：
+
+```bash
+repo-memory add --db TMPDIR/repo-memory.db --repo TMPDIR/repo --kind term --key AITask --summary "Plan 内嵌任务结构" --status confirmed --dep file:TMPDIR/repo/missing.txt:hard
+```
+
+- `TMPDIR/repo/missing.txt` 不存在
+
+## 输入
+
+```bash
+repo-memory verify --db TMPDIR/repo-memory.db --repo TMPDIR/repo
+repo-memory list --db TMPDIR/repo-memory.db --repo repo --status stale
+repo-memory events --db TMPDIR/repo-memory.db --id 1
+```
+
+## 预期输出
+
+- `verify` 输出包含 `verified 1 entries, 0 downgraded, 1 stale`
+- `list` 输出包含 `term:AITask [stale]`
+- `events` 输出包含 `marked_stale (confirmed -> stale)`
+
+## 断言结论
+
+- 缺失的硬依赖会让知识条目直接过期，而不是只进入待复核状态
+- `stale` 与 `needs_review` 是两种不同的 verify 结果
@@ -0,0 +1,25 @@
+# Case: `verify-prints-no-repos-when-empty`
+
+## 用例意义
+
+验证 `verify` 在已初始化但尚未注册任何 repo 的数据库上返回稳定空结果文本。
+
+## 前置条件
+
+- 空数据库已完成 `init`
+
+## 输入
+
+```bash
+repo-memory verify --db TMPDIR/repo-memory.db
+```
+
+## 预期输出
+
+- 命令退出码为 `0`
+- stdout 等于 `no repos`
+
+## 断言结论
+
+- 没有 tracked repo 时，`verify` 走正常空结果路径
+- 调用方可以先跑 `verify`，再根据 `no repos` 决定是否需要补充 `add` 或 `ingest`
@@ -0,0 +1,28 @@
+# Case: `verify-skips-explicit-repo-without-git-head`
+
+## 用例意义
+
+验证 `verify --repo <path>` 在目标目录不是 Git repo 或没有 HEAD commit 时，会返回稳定 skip 文本，而不是失败。
+
+## 前置条件
+
+- `TMPDIR/repo` 目录存在，但不是 Git repo，或者已经 `git init` 但还没有第一次 commit
+- 空数据库已完成 `init`
+
+## 输入
+
+```bash
+repo-memory verify --db TMPDIR/repo-memory.db --repo TMPDIR/repo
+repo-memory repos --db TMPDIR/repo-memory.db
+```
+
+## 预期输出
+
+- `verify` 退出码为 `0`
+- `verify` 输出包含 `TMPDIR/repo: skipped (not a git repo or no HEAD)`
+- `repos` 输出 `no repos`
+
+## 断言结论
+
+- 对显式 repo 的 verify，缺失 Git HEAD 被视为可跳过状态，不是命令失败
+- skip 发生在 repo 注册之前，因此不会额外写入 repo 记录