@andares/pi-toolkits 0.10.0 → 0.11.0

package/README.md

@@ -56,6 +56,7 @@ After installing, verify in any pi session:
   - [🔎 review — third-party code review](#review)
   - [🗜️ compact — dedicated compaction model](#compact)
   - [🚀 autostart — session startup automation](#autostart)
+  - [🧠 init — agent memory framework](#init)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -75,6 +76,7 @@ After installing, verify in any pi session:
 | 🔎 **review** third-party code review | `/third-review` | summon the configured review model to check + fix the task just finished, focusing on "is this round's requirement implemented / is anything missing / is anything wrong" |
 | 🗜️ **compact** dedicated compaction model | `/compact-model` | give `/compact` and auto-compact a cheap fast model to summarize with, leaving the main model free to focus on the conversation; zero overhead when unconfigured, falls back to pi's default on any failure |
 | 🚀 **autostart** session startup automation | `.pi/autostart.toml` | declare slash commands to run automatically at session start, per project (first use case: mounting multi-repo directories with `/add-dir`); never runs in untrusted directories, unregistered commands are skipped instead of being sent to the model |
+| 🧠 **init** agent memory framework | `/ask-init` | install or adopt a fixed memory layout (`AGENTS.md` + `specs/` + `.agents/memory` + `.agents/implementations`), migrate an existing one with a snapshot and a coverage table, and audit it later for drift, budgets and duplicated facts |
 
 ---
 
@@ -367,6 +369,87 @@ An **identical command line** declared by both sources runs once: a duplicate is
 
 ---
 
+## 🧠 init — agent memory framework
+
+<a name="init"></a>
+
+`/ask-init` installs one opinionated memory shape into a project, or adopts the
+documentation that is already there. The point is not the directory names — it is
+the split between three things that decay when mixed:
+
+| Family | Location | Answers | Lifetime |
+| --- | --- | --- | --- |
+| **plan** | `specs/` (`PLAN.md` + `<unit>.md`) | what to do, how it will be accepted | written before work, status updated at close |
+| **memory** | `.agents/memory/` | what is known, decided, and why | long-lived; append and compact only |
+| **evidence** | `.agents/implementations/` | what changed, when, with what proof | one record per change, never rewritten |
+
+Only agent-facing material moves under the hidden `.agents/` directory, so the
+repository root stays readable: `AGENTS.md`, `specs/`, `design/`, `docs/`,
+`legal/` remain visible and reviewable.
+
+**Commands**:
+
+| Command | What it does |
+| --- | --- |
+| `/ask-init` | detect → show the plan → (confirm) → move/scaffold/snapshot → dispatch the prose work to the model |
+| `/ask-init plan [--deep]` | print the plan and write nothing (`--dry-run` is the same) |
+| `/ask-init check` | audit the installed framework (read-only; writes only a runtime report under `.agents/framework/reports/`) |
+| `/ask-init roots` | sync the directories added with `pi-add-dir` into the framework state |
+| `/ask-init --yes` | skip the confirmation panel |
+| `/ask-init --lang zh\|en` | language for generated prose (default: detected from the project's own docs) |
+
+**What the mechanical half guarantees**:
+
+1. **Snapshot first** — every path the run may write (including every file whose
+   path references are rewritten) is copied to `.agents/framework/snapshots/<stamp>/`
+   with a sha256 manifest and the `git status` of that moment.
+2. **Writes stay inside the repository** — added roots are never written from
+   extension code; a scope card there is an ordinary tool call and therefore goes
+   through the permission gate.
+3. **Nothing is clobbered** — a create skips an existing path; a move refuses a
+   non-empty destination and turns the conflict into a manual task.
+4. **Counts reconcile** — the reference rewrite uses the same bare-reference
+   predicate as the survey, so "N occurrences in M files" from the plan is what
+   the run reports (and the rewrite report lists every file).
+5. **No silent loss** — a coverage table (`.agents/framework/reports/coverage-*.md`)
+   gets one row per migrated source section: found, declared with a destination, or
+   open with a reason. The audit fails while any row is open.
+
+The prose half is a bounded work order with acceptance criteria per task: fill the
+entry, merge the legacy plan, triage `todos/` into specs, deduplicate sections,
+record budget debt, fill the coverage table. The model closes its own loop with the
+`framework_audit` tool (activated for the run only).
+
+**Migration of an existing project** moves `memory/`, `implementations/`,
+`prompts/` under `.agents/` (one `git mv` each), moves `memory/PLAN.md` to
+`specs/PLAN.md` byte-identically, and rewrites path references — with the counts
+reported before and after. `todos/` is retired: requirement wording goes into the
+unit spec verbatim. The default pass is conservative: install, fix mechanical
+drift (tombstones, duplicated sections, appendix order), and record an over-budget
+`AGENTS.md` as debt instead of rewriting prose; `--deep` opts into structural edits.
+
+**Audit codes** (stable, so reports compare across runs): `E-PATH-01` bare legacy
+paths, `E-STATE-01` memory gitignored, `W-STATE-01` memory not yet committed, `E-INDEX-01` index ↔ file
+mismatch, `E-LINK-01` broken internal links, `W-BUDGET-01` `AGENTS.md` over budget,
+`W-DUP-01` the same section in two files, `W-ORDER-01` sections appended after the
+appendix, `W-COV-01` open coverage rows, `W-TODO-01` retired `todos/` still present,
+`W-ROOT-02` zero-byte root files, `W-SCAFFOLD-01` unfilled `TODO(ask-init)` markers,
+`I-INSTALL-01` framework not installed yet.
+
+**Multi-repository workspaces**: memory lives in the main repository only.
+`pi-add-dir` injects each added root's `AGENTS.md` verbatim into every request, so a
+root entry must stay a **scope card** (≤30 lines: what lives there, its commands,
+which main-repo memory file describes it) — never a second copy of the rules.
+
+The framework contract shipped into a project is English (it is read by models and
+published); text written *into* a project follows that project's language.
+
+> **After the run**, `/reload` so the new `AGENTS.md` enters the prompt. The
+> framework version lives in `.agents/framework/state.toml`; a project whose state
+> version is newer than the installed tool is never migrated.
+
+---
+
 ## 🛠️ Development
 
 <a name="development"></a>

package/README.zh-CN.md

@@ -56,6 +56,7 @@ pi -e ./src/index.ts
   - [🔎 review — 第三方代码评审](#review)
   - [🗜️ compact — 独立压缩模型](#compact)
   - [🚀 autostart — 会话启动自动化](#autostart)
+  - [🧠 init — agent 记忆框架](#init)
 - [开发](#development)
 - [贡献](#contributing)
 - [许可](#license)
@@ -75,6 +76,7 @@ pi -e ./src/index.ts
 | 🔎 **review** 第三方代码评审 | `/third-review` | 召唤配置的评审模型,对刚完成的任务做查+修,重点检查「本轮需求实现 / 是否有遗漏 / 是否有错误」 |
 | 🗜️ **compact** 独立压缩模型 | `/compact-model` | 给 `/compact` 与 auto-compact 配一个便宜快模型做总结,主模型专注对话;未配置零开销、任何异常回落 pi 默认 |
 | 🚀 **autostart** 会话启动自动化 | `.pi/autostart.toml` | 项目内声明启动时自动执行的斜杠命令(首批用例:`/add-dir` 多仓库挂载);未信任不执行、未注册命令跳过不发给模型 |
+| 🧠 **init** agent 记忆框架 | `/ask-init` | 安装或接管一套固定的记忆结构(`AGENTS.md` + `specs/` + `.agents/memory` + `.agents/implementations`),带快照与覆盖表迁移旧文档,之后可随时审计漂移、预算与重复事实 |
 
 ---
 
@@ -367,6 +369,71 @@ run = [
 
 ---
 
+## 🧠 init — agent 记忆框架
+
+<a name="init"></a>
+
+`/ask-init` 给项目安装一套有明确立场的记忆结构,或者接管项目里已经存在的文档。
+重点不是目录名,而是把三样混在一起必然腐烂的东西分开:
+
+| 家庭 | 位置 | 回答什么 | 生命周期 |
+| --- | --- | --- | --- |
+| **计划** | `specs/`(`PLAN.md` + `<unit>.md`) | 要做什么、怎么验收 | 开工前写,结项时更新状态 |
+| **记忆** | `.agents/memory/` | 已知什么、定过什么、为什么 | 长期;只追加、只压缩 |
+| **证据** | `.agents/implementations/` | 改了什么、什么时候、证据在哪 | 一次写定,不再改写 |
+
+只有「纯给 agent 看」的东西进隐藏目录 `.agents/`,所以仓库根仍然清爽:
+`AGENTS.md`、`specs/`、`design/`、`docs/`、`legal/` 都留在外面可读可审。
+
+**命令**:
+
+| 命令 | 作用 |
+| --- | --- |
+| `/ask-init` | 检测 → 出计划 → 确认 → 移动/脚手架/快照 → 把正文工作派发给模型 |
+| `/ask-init plan [--deep]` | 只打印计划,不写任何盘(`--dry-run` 同义) |
+| `/ask-init check` | 审计已装的框架(只读;只在 `.agents/framework/reports/` 留下运行期报告) |
+| `/ask-init roots` | 把 `pi-add-dir` 添加的目录同步进框架状态 |
+| `/ask-init --yes` | 跳过确认面板 |
+| `/ask-init --lang zh\|en` | 生成正文的语言(默认按项目自身文档判定) |
+
+**机械那一半保证什么**:
+
+1. **先快照再动** —— 本次可能写的每一条路径(包括所有会被改写的引用文件)都复制到
+   `.agents/framework/snapshots/<stamp>/`,并带 sha256 清单与当时的 `git status`。
+2. **只写仓内** —— 扩展代码绝不写 added root;在那里建 scope card 是普通工具调用,
+   因此会经过权限闸门。
+3. **不覆盖** —— 创建时已存在的文件跳过;移动时目标非空则拒绝,并转成人工任务。
+4. **计数对账** —— 引用改写与检测用同一个「裸路径」判定,计划里的「N 处 / M 个文件」
+   就是运行时报告的数字(并附逐文件清单)。
+5. **不静默丢内容** —— 迁移的每个源章节在覆盖表里都有一行:命中、声明去向、或标记
+   OPEN 并写理由;只要还有 OPEN,审计就不算通过。
+
+正文那一半是一份带验收标准的工作单:填空入口、合并旧计划、把 `todos/` 收敛进 specs、
+去重章节、登记预算债务、填覆盖表。模型用只在本轮激活的 `framework_audit` 工具自检收口。
+
+**迁移既有项目**会把 `memory/`、`implementations/`、`prompts/` 移到 `.agents/` 下
+(逐个 `git mv`),把 `memory/PLAN.md` 原样搬到 `specs/PLAN.md`,再改写路径引用,
+前后计数都会报出来。`todos/` 退役:需求原文原样进对应单元的 spec。默认是**保守 pass**:
+装框架、修机械漂移(墓碑、重复章节、附录顺序),超预算的 `AGENTS.md` 只登记成债务;
+`--deep` 才允许结构性改写。
+
+**审计码**(稳定,可跨次对比):`E-PATH-01` 裸旧路径、`E-STATE-01` 记忆被 gitignore、`W-STATE-01` 记忆尚未提交、`E-INDEX-01` 索引与实际文件不一致、`E-LINK-01` 内部链接失效、
+`W-BUDGET-01` `AGENTS.md` 超预算、`W-DUP-01` 同一章节出现在两个文件、
+`W-ORDER-01` 附录之后又追加章节、`W-COV-01` 覆盖表仍有 OPEN、
+`W-TODO-01` 仍存在退役的 `todos/`、`W-ROOT-02` 根下零字节文件、
+`W-SCAFFOLD-01` 未填的 `TODO(ask-init)` 标记、`I-INSTALL-01` 尚未安装框架。
+
+**多仓库工作区**:记忆只住主仓。`pi-add-dir` 会把每个 added root 的 `AGENTS.md`
+全文注入每次请求,所以根里的入口只能是 **scope card**(≤30 行:这里放什么、它的命令、
+去主仓哪个记忆文件读),绝不能是规则的第二份副本。
+
+装进项目的框架契约用英文(给模型读、也随 npm 发布);写进项目的正文跟随项目语言。
+
+> **跑完记得 `/reload`**,让新的 `AGENTS.md` 进入提示词。框架版本记在
+> `.agents/framework/state.toml`;若项目的状态版本比当前工具新,则拒绝迁移。
+
+---
+
 ## 🛠️ 开发
 
 <a name="development"></a>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.10.0",
-  "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), session-scoped permission checks, model favorites, prompt stash, third-party code review, session autostart, and a dedicated compaction model",
+  "version": "0.11.0",
+  "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), session-scoped permission checks, model favorites, prompt stash, third-party code review, session autostart, a dedicated compaction model, and an agent memory framework (/ask-init)",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,11 @@
     "autostart",
     "permission",
     "approval",
-    "boundary"
+    "boundary",
+    "agent-memory",
+    "memory-framework",
+    "scaffold",
+    "init"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.99.0",

package/src/features/init/analyze.ts

@@ -0,0 +1,162 @@
+/**
+ * init feature — pure document analysis shared by the planner and the auditor.
+ *
+ * These helpers answer questions about *documents*, not about the filesystem:
+ * duplicated sections, tombstones, appendix ordering, oversized sections and
+ * path references. Keeping them here means the plan's warnings and the audit's
+ * findings cannot drift apart.
+ */
+import type { DocInfo, Heading } from "./types.js";
+
+/** Normalise a heading for comparison: drop numbering, markup, emoji, case. */
+export function normalizeHeading(text: string): string {
+	return text
+		.replace(/^[§#\s]*\d+(?:[.\-–]\d+)*[.、:)]?\s*/, "")
+		.replace(/[`*_~[\]]/g, "")
+		.replace(/[\p{Emoji_Presentation}\p{Extended_Pictographic}]/gu, "")
+		.replace(/[\s\u3000]+/g, "")
+		.replace(/[：:，,。.、（）()]/g, "")
+		.toLowerCase();
+}
+
+/** H2 headings (level 2 only) of a document. */
+export function topSections(doc: DocInfo): Heading[] {
+	return doc.headings.filter((heading) => heading.level === 2);
+}
+
+export interface DuplicateGroup {
+	readonly normalized: string;
+	readonly occurrences: Array<{ path: string; heading: string; line: number }>;
+}
+
+/** Same H2 heading appearing in two or more documents. */
+export function duplicateHeadings(docs: readonly DocInfo[]): DuplicateGroup[] {
+	const groups = new Map<string, DuplicateGroup["occurrences"]>();
+	for (const doc of docs) {
+		for (const heading of topSections(doc)) {
+			const key = normalizeHeading(heading.text);
+			if (key.length < 2) continue;
+			const list = groups.get(key) ?? [];
+			list.push({ path: doc.rel, heading: heading.text, line: heading.line });
+			groups.set(key, list);
+		}
+	}
+	const out: DuplicateGroup[] = [];
+	for (const [normalized, occurrences] of groups) {
+		if (occurrences.length < 2) continue;
+		// Same file twice is a different problem (repeated section), still useful.
+		out.push({ normalized, occurrences });
+	}
+	return out.sort((a, b) => b.occurrences.length - a.occurrences.length);
+}
+
+/** Section bodies as `[heading, body]`, body ending at the next same-or-higher heading. */
+export function sectionBodies(doc: DocInfo): Array<{ heading: Heading; body: string }> {
+	const lines = doc.text.split("\n");
+	const out: Array<{ heading: Heading; body: string }> = [];
+	for (const heading of doc.headings) {
+		if (heading.level !== 2) continue;
+		const start = heading.line; // 0-based index of the line *after* the heading
+		let end = lines.length;
+		for (const other of doc.headings) {
+			if (other.line <= heading.line) continue;
+			if (other.level <= 2) {
+				end = other.line - 1;
+				break;
+			}
+		}
+		out.push({ heading, body: lines.slice(start, end).join("\n").trim() });
+	}
+	return out;
+}
+
+const POINTER_PHRASES =
+	/(已迁|迁至|移至|见\s*`|参见\s*`|moved to|see\s+`|已并入|merged into)/i;
+
+/**
+ * A "tombstone": a section whose whole body is a one-line pointer to wherever
+ * the content went. After the move is registered in the index such sections are
+ * pure noise, so the plan asks for their removal.
+ */
+export function tombstones(doc: DocInfo): Heading[] {
+	const out: Heading[] = [];
+	for (const { heading, body } of sectionBodies(doc)) {
+		if (body.length === 0 || body.length > 220) continue;
+		if (!POINTER_PHRASES.test(body)) continue;
+		const meaningful = body
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line.length > 0 && !line.startsWith("|"));
+		if (meaningful.length <= 3) out.push(heading);
+	}
+	return out;
+}
+
+/**
+ * Headings that sit after the historical appendix started. Appendices are the
+ * last thing in a document by convention; dated sections appended later mean
+ * the file grew without a compacting pass.
+ */
+export function sectionsAfterAppendix(doc: DocInfo): Heading[] {
+	const sections = topSections(doc);
+	const firstAppendix = sections.findIndex((heading) =>
+		/^(附录|appendix)/i.test(heading.text.trim()),
+	);
+	if (firstAppendix < 0) return [];
+	return sections
+		.slice(firstAppendix + 1)
+		.filter((heading) => !/^(附录|appendix)/i.test(heading.text.trim()));
+}
+
+/** The N largest H2 sections, with their character counts (split candidates). */
+export function largestSections(
+	doc: DocInfo,
+	limit = 3,
+): Array<{ heading: Heading; chars: number }> {
+	return sectionBodies(doc)
+		.map(({ heading, body }) => ({ heading, chars: body.length }))
+		.sort((a, b) => b.chars - a.chars)
+		.slice(0, limit);
+}
+
+/**
+ * Paths mentioned in a document that the framework can verify: memory files,
+ * specs, implementation records. Returned without the surrounding backticks so
+ * callers can `existsSync` them directly.
+ */
+export function extractFrameworkPaths(text: string): string[] {
+	const out = new Set<string>();
+	const re =
+		/(?:\.agents\/memory\/(?:[\w.\-]+\.md)|specs\/[\w./-]+\.md|\.agents\/implementations\/[\w.\-]+\.md)/g;
+	for (const match of text.matchAll(re)) out.add(match[0]);
+	return [...out];
+}
+
+/** First paragraph of a section, used as the coverage anchor. */
+export function sectionAnchor(doc: DocInfo, heading: Heading): string {
+	const lines = doc.text.split("\n");
+	let index = heading.line; // first line after the heading
+	let collected = "";
+	let started = false;
+	for (; index < lines.length; index += 1) {
+		const line = lines[index].trim();
+		if (/^#{1,6}\s/.test(line)) break;
+		if (line.length === 0) {
+			if (started) break;
+			continue;
+		}
+		if (/^([-*+]\s|\d+[.)]\s|\||>)/.test(line)) continue;
+		collected = collected.length === 0 ? line : `${collected} ${line}`;
+		started = true;
+		if (collected.length >= 80) break;
+	}
+	return collected.slice(0, 80);
+}
+
+/** Normalise prose for anchor matching (drop markdown emphasis and spacing). */
+export function normalizeProse(text: string): string {
+	return text
+		.replace(/[`*_~[\]]/g, "")
+		.replace(/[\s\u3000]+/g, "")
+		.toLowerCase();
+}

package/src/features/init/apply.test.ts

@@ -0,0 +1,264 @@
+import { describe, expect, it } from "vitest";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { applyPlan, rewriteText, stateToToml } from "./apply.js";
+import { parseState } from "./detect.js";
+import { detect } from "./detect.js";
+import { buildPlan } from "./plan.js";
+import { installedProject, project, remove } from "./test-helpers.js";
+import type { Plan } from "./types.js";
+
+const ORIGINAL_PLAN = "# 计划\n\n## 路线\n\n- M1 未完成\n";
+const LEGACY: Record<string, string> = {
+	"AGENTS.md": [
+		"# demo — 项目指南",
+		"",
+		"细节记忆放在 `memory/`。",
+		"",
+		"## 8. 问题清单",
+		"",
+		"已迁至 `memory/PLAN.md` §5。",
+		"",
+	].join("\n"),
+	"memory/PLAN.md": ORIGINAL_PLAN,
+	"memory/FINISHED.md": "# 已完成\n\n## 摘要\n\n- M0：见 `implementations/2026-01-01_a.md`\n",
+	"memory/ARCHITECTURE.md": "# 架构\n\n## 分层\n\n- 见 `memory/DESIGN.md`\n",
+	"memory/DESIGN.md": "# 视觉\n",
+	"implementations/2026-01-01_a.md": "# a\n\n见 `memory/ARCHITECTURE.md`。\n",
+	"specs/a.md": "# a\n\n证据：`implementations/2026-01-01_a.md`。\n",
+	"todos/2026-01-02-x.md": "# 原始需求\n\n做点事。\n",
+	"src/a.ts": "// 见 `memory/DESIGN.md`\n",
+};
+
+function planFor(root: string): Plan {
+	return buildPlan(detect(root), {
+		toolVersion: "test",
+		now: new Date("2026-10-26T10:00:00+08:00"),
+	});
+}
+
+describe("rewriteText", () => {
+	const pairs = [
+		{ from: "memory/PLAN.md", to: "specs/PLAN.md" },
+		{ from: "memory/", to: ".agents/memory/" },
+	];
+
+	it("applies the longest prefix first", () => {
+		const result = rewriteText("see `memory/PLAN.md` and `memory/X.md`", pairs);
+		expect(result.text).toBe("see `specs/PLAN.md` and `.agents/memory/X.md`");
+		expect(result.hits).toBe(2);
+	});
+
+	it("leaves already-migrated paths and path tails alone", () => {
+		const result = rewriteText("`.agents/memory/X.md` ~/.pi/agent/memory/y", pairs);
+		expect(result.text).toBe("`.agents/memory/X.md` ~/.pi/agent/memory/y");
+		expect(result.hits).toBe(0);
+	});
+});
+
+describe("applyPlan", () => {
+	it("moves the legacy layout, rewrites references and keeps the originals", () => {
+		const root = project(LEGACY);
+		try {
+			const plan = planFor(root);
+			const expectedHits = plan.facts.refs.hits;
+			const applied = applyPlan(plan, { now: new Date("2026-10-26T10:00:00+08:00") });
+
+			expect(existsSync(join(root, "memory"))).toBe(false);
+			expect(existsSync(join(root, "implementations"))).toBe(false);
+			expect(existsSync(join(root, ".agents/memory/FINISHED.md"))).toBe(true);
+			expect(existsSync(join(root, ".agents/implementations/2026-01-01_a.md"))).toBe(true);
+
+			// The plan file moves byte-identically; the model shapes it afterwards.
+			expect(readFileSync(join(root, "specs/PLAN.md"), "utf8")).toBe(ORIGINAL_PLAN);
+
+			// References are rewritten in prose and code alike.
+			expect(readFileSync(join(root, "src/a.ts"), "utf8")).toContain(".agents/memory/DESIGN.md");
+			expect(readFileSync(join(root, "specs/a.md"), "utf8")).toContain(
+				".agents/implementations/2026-01-01_a.md",
+			);
+			const agents = readFileSync(join(root, "AGENTS.md"), "utf8");
+			expect(agents).toContain(".agents/memory/");
+			expect(agents).toContain("specs/PLAN.md");
+
+			// Snapshot keeps the pre-move bytes (and therefore the old paths).
+			expect(applied.snapshot?.dir).toMatch(/^\.agents\/framework\/snapshots\//);
+			const snapshotFile = join(root, applied.snapshot?.dir ?? "", "files/src/a.ts");
+			expect(readFileSync(snapshotFile, "utf8")).toContain("memory/DESIGN.md");
+			expect(existsSync(join(root, applied.snapshot?.dir ?? "", "manifest.json"))).toBe(true);
+
+			// Counts reconcile with the survey.
+			expect(applied.rewrites?.hits).toBe(expectedHits);
+
+			// State, work order and coverage worklist exist and are readable.
+			expect(applied.statePath).toBe(".agents/framework/state.toml");
+			const state = parseState(readFileSync(join(root, ".agents/framework/state.toml"), "utf8"));
+			expect(state.version).toBe(1);
+			expect(state.migrations.length).toBeGreaterThan(0);
+			expect(state.lang).toBe("zh");
+			expect(applied.planPath).toMatch(/^\.agents\/framework\/plans\/plan-.*\.json$/);
+			const order = JSON.parse(readFileSync(join(root, applied.planPath ?? ""), "utf8")) as {
+				tasks: Array<{ id: string }>;
+			};
+			expect(order.tasks.map((task) => task.id)).toContain("triage-todos");
+			expect(applied.created).toContain(".agents/memory/README.md");
+
+			expect(plan.artifacts.coverage).toMatch(/^\.agents\/framework\/reports\/coverage-.*\.md$/);
+			const coverage = readFileSync(join(root, plan.artifacts.coverage ?? ""), "utf8");
+			expect(coverage).toContain("OPEN");
+			expect(coverage).toContain("AGENTS.md");
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("is safe to run twice", () => {
+		const root = project(LEGACY);
+		try {
+			const plan = planFor(root);
+			applyPlan(plan, { now: new Date("2026-10-26T10:00:00+08:00") });
+			const second = applyPlan(plan, { now: new Date("2026-10-26T10:05:00+08:00") });
+			expect(second.moved).toHaveLength(0);
+			expect(second.rewrites?.hits).toBe(0);
+			expect(second.skipped.length).toBeGreaterThan(0);
+			expect(existsSync(join(root, ".agents/memory/FINISHED.md"))).toBe(true);
+			expect(existsSync(join(root, "memory"))).toBe(false);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("writes nothing on a dry run", () => {
+		const root = project(LEGACY);
+		try {
+			const plan = planFor(root);
+			applyPlan(plan, {
+				dryRun: true,
+				now: new Date("2026-10-26T10:00:00+08:00"),
+			});
+			expect(existsSync(join(root, "memory"))).toBe(true);
+			expect(existsSync(join(root, ".agents"))).toBe(false);
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("does not merge two copies of a directory on its own", () => {
+		const root = installedProject({
+			"memory/FINISHED.md": "# old finished\n",
+		});
+		try {
+			const plan = planFor(root);
+			expect(plan.mode).toBe("reconcile");
+			applyPlan(plan, { now: new Date("2026-10-26T10:00:00+08:00") });
+			expect(existsSync(join(root, "memory/FINISHED.md"))).toBe(true);
+			expect(readFileSync(join(root, ".agents/memory/FINISHED.md"), "utf8")).toContain("Summary");
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("round-trips state through TOML", () => {
+		const root = installedProject();
+		try {
+			const plan = planFor(root);
+			const state = {
+				version: 1,
+				tool: "9.9.9",
+				created: "2026-01-01T00:00:00+08:00",
+				updated: "2026-01-02T00:00:00+08:00",
+				profile: "core" as const,
+				modules: ["design"],
+				lang: "zh" as const,
+				roots: [
+					{
+						label: "api",
+						path: "../api",
+						absolute: "/tmp/api",
+						role: "backend",
+						agentsMd: "scope-card" as const,
+						source: "add-dir" as const,
+						exists: true,
+						lastSeen: "2026-01-02T00:00:00+08:00",
+					},
+				],
+				managed: [],
+				migrations: [{ at: "2026-01-02T00:00:00+08:00", to: "1", notes: "adopt" }],
+			};
+			const parsed = parseState(stateToToml(state));
+			expect(parsed.roots[0]).toMatchObject({ label: "api", agentsMd: "scope-card" });
+			expect(parsed.migrations[0].notes).toBe("adopt");
+			expect(parsed.budgets).toBeUndefined();
+			void plan;
+		} finally {
+			remove(root);
+		}
+	});
+});
+
+
+describe("review regressions", () => {
+	it("preserves relative prefixes while rewriting", () => {
+		const result = rewriteText("see `../memory/A.md` and `./implementations/B.md`", [
+			{ from: "memory/", to: ".agents/memory/" },
+			{ from: "implementations/", to: ".agents/implementations/" },
+		]);
+		expect(result.text).toBe(
+			"see `../.agents/memory/A.md` and `./.agents/implementations/B.md`",
+		);
+		expect(result.hits).toBe(2);
+	});
+
+	it("records managed hashes after the reference rewrite", () => {
+		const root = project(LEGACY);
+		try {
+			applyPlan(planFor(root), { now: new Date("2026-10-26T10:00:00+08:00") });
+			const state = parseState(readFileSync(join(root, ".agents/framework/state.toml"), "utf8"));
+			for (const entry of state.managed) {
+				const digest = createHash("sha256")
+					.update(readFileSync(join(root, entry.path)))
+					.digest("hex");
+				expect(entry.sha256, entry.path).toBe(digest);
+			}
+		} finally {
+			remove(root);
+		}
+	});
+
+	it("moves a root-level PLAN.md into the plan home", () => {
+		const root = project({
+			"AGENTS.md": "# demo\n\nSee `PLAN.md`.\n",
+			"PLAN.md": "# Plan\n\n## Route\n\n- open item\n",
+		});
+		try {
+			const plan = planFor(root);
+			const move = plan.actions.find((action) => action.kind === "move-file");
+			expect(move && move.kind === "move-file" ? move.from : "").toBe("PLAN.md");
+			expect(plan.tasks.some((task) => task.id === "edit-plan")).toBe(true);
+			const applied = applyPlan(plan, { now: new Date("2026-10-26T10:00:00+08:00") });
+			expect(existsSync(join(root, "PLAN.md"))).toBe(false);
+			expect(readFileSync(join(root, "specs/PLAN.md"), "utf8")).toContain("open item");
+			// The moved source must be recoverable, not just the destination.
+			expect(
+				existsSync(join(root, applied.snapshot?.dir ?? "", "files/PLAN.md")),
+			).toBe(true);
+		} finally {
+			remove(root);
+		}
+	});
+});
+
+
+it("does not corrupt non-UTF-8 files during reference rewriting", () => {
+	const root = project(LEGACY);
+	try {
+		const latin = Buffer.from("// see `memory/DESIGN.md` — caf\xe9\n", "latin1");
+		writeFileSync(join(root, "src/latin1.ts"), latin);
+		applyPlan(planFor(root), { now: new Date("2026-10-26T10:00:00+08:00") });
+		expect(readFileSync(join(root, "src/latin1.ts"))).toEqual(latin);
+		expect(readFileSync(join(root, "src/a.ts"), "utf8")).toContain(".agents/memory/DESIGN.md");
+	} finally {
+		remove(root);
+	}
+});