@andares/pi-toolkits 0.10.0 → 0.11.1

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 |
 
 ---
 
@@ -114,7 +116,7 @@ Enter with `/ask` (press it again to exit). Meant for the case where you only wa
 
 Repeating the argument form with the modes already in force is a **no-op**: no second "ON" notice and no loss of the session grants collected so far. Changing any mode records the change and clears those grants, because they were made under the old policy.
 
-**Defaults**: in-project read/write allowed, outside read allowed, outside write asks.
+**Defaults**: in-project read/write allowed, outside read allowed, outside write asks — except writes under the OS temp root, which are scratch space and pass directly. An explicit `out write = deny` still denies them.
 
 | Scope | reads | writes / exec |
 | --- | --- | --- |
@@ -123,19 +125,22 @@ Repeating the argument form with the modes already in force is a **no-op**: no s
 
 `exec` is folded into `write`: any command that changes state counts as a write.
 
+**Temporary write zone**: a write outside the project but under the OS temp root (`os.tmpdir()`, `/var/tmp`, `/dev/shm`) is allowed without a dialog when `out write` is `ask` (the audit layer is `temp`). `/tmp` is shared scratch space, so this is a convenience rule, not an isolation boundary; deleting a temp root itself (`rm -rf /tmp`) still hits the destructive table.
+
 **What is inspected**
 
 - **bash** is decomposed into simple commands — `&&`, `||`, `;`, pipes, `$(…)`, backticks, `bash -c`, `eval`, the common indirection wrappers (`sudo`, `env`, `xargs`, `find -exec`, …), heredocs — and judged per command. `cd` folds into the commands after it; the strictest result wins, so `cd /tmp && rm x` cannot ride on the first segment.
 - **path-bearing tools** (`read` / `write` / `edit` / `grep` / `find` / `ls`) are judged by their own path; every other tool is judged by the working directory.
 - **unresolvable input** — a non-literal `cd` or `git -C`, an unknown shell variable in a path, an unterminated heredoc or substitution — is asked about regardless of mode (fail closed), never guessed.
 - **`git -C <dir>`** is resolved like a local `cd`: relative path arguments (and the repository) are judged against `<dir>`, not the working directory.
+- **device sinks and data arguments** — `/dev/null`, `/dev/stdout` and `/dev/stderr` are never boundary targets, whether written as a redirect (`cmd > /dev/null`) or an operand (`curl -o /dev/null`); the arguments of `echo` / `printf` are data, not paths.
 
 **Answers**: `a` allow once · `s` allow this directory for the session · `d` deny · `f` deny this directory for the session. Session grants are kept in memory as `(read|write, directory)`, matched by containment, and cleared when the mode is turned off or the session ends. A session grant outranks the destructive table — once you have allowed an operation for the session, repeating it does not ask again. A command the parser cannot resolve is granted by its exact text instead, so repeating the same opaque command does not ask again.
 
 **Fixed safety tables** (independent of the four modes):
 
 - **credentials are denied in every mode** — `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.pi/agent/auth*.json`, `.env` files (templates excepted). Without this, `out read = allow` would hand out `~/.ssh/id_rsa`.
-- **destructive commands always ask** — `rm` of `/`, the home directory, or the working directory; `git reset --hard`; `git clean -f`; `git push --force`; package `publish`; `dd` to a raw device; `mkfs*`; shutdown/reboot; `chmod -R 777`; anything through `sudo`. Scope alone cannot express "destructive".
+- **destructive commands always ask** — `rm` of `/`, the home directory, the working directory, or a temp root (`/tmp`, `/var/tmp`, `/dev/shm`); `git reset --hard`; `git clean -f`; `git push --force`; package `publish`; `dd` to a raw device; `mkfs*`; shutdown/reboot; `chmod -R 777`; anything through `sudo`. Scope alone cannot express "destructive".
 
 **Approval log** (write-only telemetry, on by default)
 
@@ -367,6 +372,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`),带快照与覆盖表迁移旧文档,之后可随时审计漂移、预算与重复事实 |
 
 ---
 
@@ -114,7 +116,7 @@ pi -e ./src/index.ts
 
 参数形式重复执行、且四项模式与当前一致时是**空操作**:不会再出一条「ON」提示,也不会清掉已经攒下的会话授权。只有模式真的变了才会提示并清空授权——那些授权是按旧策略给的。
 
-**默认值**:项目内读/写全放行,项目外读放行,项目外写询问。
+**默认值**:项目内读/写全放行,项目外读放行,项目外写询问——但 `os.tmpdir()`、`/var/tmp`、`/dev/shm` 下的临时写入直接放行。显式把 `out write` 设为 `deny` 时仍然拒绝。
 
 | 作用域 | 读 | 写 / 执行 |
 | --- | --- | --- |
@@ -123,19 +125,22 @@ pi -e ./src/index.ts
 
 `exec` 折进 `write`:任何产生变更的执行都算写。
 
+**临时写入区**:项目外、但落在操作系统临时根(`os.tmpdir()`、`/var/tmp`、`/dev/shm`)的写入,在 `out write = ask` 时直接放行(审计层记 `temp`)。`/tmp` 是共享草稿空间,这条是便利规则,不是隔离边界;**删除临时根本身**(`rm -rf /tmp`)仍然走破坏性表。
+
 **检查方式**
 
 - **bash** 先拆成简单命令 —— `&&`、`||`、`;`、管道、`$(…)`、反引号、`bash -c`、`eval`、常见间接包装(`sudo`、`env`、`xargs`、`find -exec`…)、heredoc —— 再逐条判定;`cd` 向前折叠,取最严格的结果,所以 `cd /tmp && rm x` 不会靠第一段蒙混过关
 - **带路径的工具**(`read` / `write` / `edit` / `grep` / `find` / `ls`)按自己的路径判定;其它工具按工作目录判定
 - **无法解析的输入** —— 非字面量 `cd` 或 `git -C`、路径里的未知 shell 变量、未闭合的 heredoc/命令替换 —— 一律询问,不看模式(fail closed),绝不猜测
 - **`git -C <dir>`** 按局部 `cd` 处理:相对路径参数(和仓库本身)按 `<dir>` 判定,而不是工作目录
+- **设备 sink 与数据参数** —— `/dev/null`、`/dev/stdout`、`/dev/stderr` 无论是重定向(`cmd > /dev/null`)还是普通操作数(`curl -o /dev/null`),都不算边界目标;`echo` / `printf` 的参数是数据,不按路径处理
 
 **回答**:`a` 本次允许 · `s` 本会话允许该目录 · `d` 拒绝 · `f` 本会话拒绝该目录。会话授权在内存中按 `(读|写, 目录)` 保存、按包含关系匹配,关闭模式或会话结束时清空;**会话授权优先于破坏性表**——你按了 `s` 之后,重复同一操作不会再弹;解析不了完整路径的命令则按**完整命令文本**授权,重复同一条命令不会再问。
 
 **固定安全表**(与四格模式无关):
 
 - **凭据路径任何模式都拒绝** —— `~/.ssh`、`~/.gnupg`、`~/.aws`、`~/.pi/agent/auth*.json`、`.env` 文件(模板除外)。没有这一条,默认的「项目外读放行」就等于把 `~/.ssh/id_rsa` 交出去
-- **破坏性命令永远询问** —— 对 `/`、家目录或工作目录的 `rm`;`git reset --hard`;`git clean -f`;`git push --force`;包 `publish`;`dd` 写裸设备;`mkfs*`;关机/重启;`chmod -R 777`;任何经 `sudo` 的命令。作用域本身表达不了「破坏性」
+- **破坏性命令永远询问** —— 对 `/`、家目录、工作目录或临时根(`/tmp`、`/var/tmp`、`/dev/shm`)的 `rm`;`git reset --hard`;`git clean -f`;`git push --force`;包 `publish`;`dd` 写裸设备;`mkfs*`;关机/重启;`chmod -R 777`;任何经 `sudo` 的命令。作用域本身表达不了「破坏性」
 
 **审批日志**(只写遥测,默认开启)
 
@@ -367,6 +372,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.1",
+  "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/ask/index.ts

@@ -1,7 +1,8 @@
 /**
  * ask feature — read-only consult mode.
  *
- * Design notes (see PLAN.md and AGENTS.md):
+ * Design notes (see AGENTS.md §Feature: ask, plus the D1–D6 records in
+ * .agents/memory/ARCHITECTURE.md):
  *  - Project writes stay impossible: write/edit/powershell are removed from the
  *    active tool set via pi.setActiveTools(), and pi's runtime rejects calls to
  *    non-active tools ("Tool not found"). A gate blocks them again as defence in

package/src/features/ask/prompt.ts

@@ -16,7 +16,8 @@
  *    be ~300 tokens per request restating what the sandbox already enforces.
  *
  * Do NOT use the removed `systemPromptAppend` field or wholesale systemPrompt
- * replacement (see PLAN.md).
+ * replacement (see `AGENTS.md` §Feature: ask and the D5 record in
+ * `.agents/memory/ARCHITECTURE.md`).
  */
 
 export interface AskBannerOptions {

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();
+}