@mingmaple/dsh-handover 0.9.22 → 1.0.0

package/src/tools/ho_checkpoint.mjs

@@ -2,26 +2,27 @@
 import { textOutput } from '../lib/output.mjs';
 import { nameOf } from '../lib/names.mjs';
 import { NL } from '../lib/text.mjs';
-import { readHandover, writeHandover } from '../lib/handover-io.mjs';
+import { readHandover, rewriteHandover } from '../lib/handover-io.mjs';
 import { eventsOf, countCompactions } from '../lib/events.mjs';
 import { decide } from '../lib/phase.mjs';
 import { checkConsent, consumedConsent } from '../lib/consent.mjs';
+import { markSkipNext } from '../lib/reminder.mjs';
 
 export function pmCheckpointTool(env) {
   return {
     name: nameOf('checkpoint'),
     description:
-      '写交接、登记压缩；回合结束后自动压缩。resume=continue（默认）压缩后续跑；resume=wait 表示任务已收尾，压缩后不唤醒。',
+      '写交接、登记压缩；回合结束后自动压缩。resume=continue（缺省）表示压缩后续跑；resume=wait 表示任务已收尾，压缩后不唤醒。',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
         handover_text: { type: 'string', description: '要写入的交接正文；不给则要求磁盘上已有合格交接' },
         handover_path: { type: 'string', description: '覆盖交接路径（演练用）' },
-        resume: { type: 'string', enum: ['continue', 'wait'], description: '压缩后的去向：continue（默认）按交接 §2 继续；wait 表示本轮任务已收尾，压缩后不唤醒，等当前用户派新任务' },
-        at_risk: { type: 'boolean', description: '当前处在关键步骤：为 true 时，水位在提醒线～交接线之间只提醒、不压缩（过交接线仍会压）' },
+        resume: { type: 'string', enum: ['continue', 'wait'], description: '压缩后的去向：continue（缺省）按交接 §2 继续；wait 表示本轮任务已收尾，压缩后不唤醒，等待当前用户派新任务' },
+        at_risk: { type: 'boolean', description: '当前处在关键步骤：为 true 时，水位在提醒线与交接线之间只提醒、不压缩（过交接线仍压缩）' },
         force: { type: 'boolean', description: '忽略关键步骤判定，直接排压缩' },
-        confirm: { type: 'boolean', description: '判定为「可压缩」后须经当前用户同意才传 true；还需当前用户在设置页点击「授权压缩」（5 分钟一次性授权），否则不排压缩' },
+        confirm: { type: 'boolean', description: '判定为「可压缩」后，须经当前用户同意方可传 true；同时须当前用户在设置页点击「授权压缩」（5 分钟一次性授权），否则不排压缩' },
       },
     },
     output: textOutput(),
@@ -37,7 +38,7 @@ export function pmCheckpointTool(env) {
         return { text: [
           '没有可用的交接路径：' + (target && target.reason ? target.reason : '未知'),
           '先指定角色（设置页的 dsh-handover 中「会话角色」），或显式传 handover_path="<交接文件绝对路径>"。',
-          '压缩会丢历史，没有合格交接就不排压缩。',
+          '压缩会丢失历史；没有合格交接，不排压缩。',
         ].join(NL) };
       }
       const file = target.path;
@@ -49,53 +50,53 @@ export function pmCheckpointTool(env) {
       const ratioText = ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%';
       const recentSec = st && st.lastSummaryMs ? (Date.now() - st.lastSummaryMs) / 1000 : null;
       if (recentSec !== null && recentSec < 120 && args.force !== true) {
-        out.push("拒绝排压缩：" + Math.round(recentSec) + " 秒前刚完成一次压缩（日志里有 compaction/summary），避免重复排程。");
-        out.push("等一轮让投影缓存刷新；确实要再压一次请加 force=true。");
+        out.push("拒绝排压缩：" + Math.round(recentSec) + " 秒前刚完成一次压缩（日志中有 compaction/summary），以免重复排程。");
+        out.push("等待一轮使投影缓存刷新；确需再次压缩，请加 force=true。");
         return { text: out.join(NL) };
       }
       if (count.lock === "open") {
         out.push("拒绝排压缩：检测到未闭合的压缩锁（compaction/start 无配对 end）。");
-        out.push("处理：等当前压缩结束后用 ho_status 复查；若长时间不动，说明上次压缩崩在中间。");
+        out.push("处置：等当前压缩结束后用 ho_status 复查；若长时间无变化，说明上次压缩中途失败。");
         return { text: out.join(NL) };
       }
       const adv = decide({ ratio, compactionsUsed: count.used, cfg: env.cfg, lockState: count.lock });
       if (adv.action === "new_session") {
         out.push("不建议压缩：" + adv.reason);
-        out.push('下一步：用 ho_handover(action=write) 写交接，再由全局 ho_sessions(action="new") 建新会话。');
+        out.push('下一步：按固定流程写交接。① ho_handover(action="read") 读旧交接；② action="archive" 归档；③ 读模板 _Control_Center/templates/Handover.md；④ action="new" 新建空白写入。之后由全局 ho_sessions(action="new") 建立新会话。');
         return { text: out.join(NL) };
       }
-      if (adv.action === "pause" && args.at_risk === true && args.force !== true) {
-        out.push("已暂停（关键步骤）：" + adv.reason);
-        out.push("到阶段边界再调一次 ho_checkpoint（不带 at_risk 或带 force）。");
+      if (args.at_risk === true && args.force !== true && ratio !== null && ratio < (env.cfg.hardRatio || 0.85)) {
+        out.push("已暂缓（关键步骤）：水位 " + ratioText + "，先完成当前小步骤再压缩；到阶段边界再调用一次 ho_checkpoint（不带 at_risk，或带 force）。");
         return { text: out.join(NL) };
       }
       if (adv.action === "continue" && args.force !== true) {
-        out.push("水位未到线（" + ratioText + "）：不压。");
-        out.push("需要强制演练可加 force=true。");
+        out.push("水位未到可压缩线（" + ratioText + "）：不压缩。");
+        out.push("需要提前压缩时，先向当前用户说明理由并取得授权，再加 force=true；当前用户主动要求时同样处理。");
         return { text: out.join(NL) };
       }
       // 判断逻辑不动；只有判定可以压缩之后，才停下来问用户。
       if (args.confirm !== true) {
         out.push('判定：可以压缩（' + adv.reason + '）。');
-        out.push('水位 ' + ratioText + '，已压缩 ' + count.used + '/3。');
-        out.push('压缩会丢历史并自动续跑 —— 先问当前用户「要压缩吗？」，回答同意后再调 ho_checkpoint(confirm=true)；不同意就保持原样。');
+        out.push('水位 ' + ratioText + '，已压缩 ' + count.used + '/' + env.cfg.maxCompactions + '。');
+        out.push('压缩会丢失历史并自动续跑。先向当前用户确认是否压缩，同意后再调用 ho_checkpoint(confirm=true)；不同意则保持原状。');
         return { text: out.join(NL) };
       }
       let wrote = null;
       if (typeof args.handover_text === "string" && args.handover_text.trim() !== "") {
-        wrote = writeHandover(ws, file, args.handover_text, "write", { kind: target.kind, info });
-        out.push("交接已写入 " + file + "（" + wrote.bytes + " B，备份：" + (wrote.backup || "无") + "）· 角色 " + info.role);
+        wrote = rewriteHandover(ws, file, args.handover_text, { kind: target.kind, info });
+        out.push("交接已写入 " + file + "（" + wrote.bytes + " B）· 角色 " + info.role);
+        if (wrote.archived) out.push("旧交接已归档 " + wrote.archived.dest + "（sha256 一致）");
         out.push("体检 " + wrote.verdict + (wrote.reasons.length ? "：" : " · 结构齐备"));
         for (const r of wrote.reasons) out.push("  - " + r);
         if (wrote.verdict !== "通过") {
-          out.push("体检不通过 ⇒ 不排压缩（先补结构，压缩后就没机会改了）。");
+          out.push("体检未通过，不排压缩（先补齐结构；压缩后无法再改）。");
           return { text: out.join(NL) };
         }
       } else {
         const cur = readHandover(file);
         if (cur.text === null || cur.text.trim() === "") {
           out.push("没有交接正文，磁盘上也没有：" + file);
-          out.push("拒绝压缩 —— 压缩会丢历史，必须先有交接。");
+          out.push("拒绝压缩：压缩会丢失历史，必须先有交接。");
           return { text: out.join(NL) };
         }
         out.push("沿用磁盘上已有交接：" + file);
@@ -105,28 +106,30 @@ export function pmCheckpointTool(env) {
       // 会话自行判断水位与询问用户，用户点授权后自行排压缩，不必上报全局。
       const cs = checkConsent(meId);
       if (!cs.ok) {
-        out.push('交接已写好，但**没有排压缩**：' + cs.reason + '。');
-        out.push('授权方式（任选其一）：① 在聊天框发送 /allow-compact（最快，仅授权本会话）；② 在设置页的 dsh-handover 中点击「授权压缩」一次。授权有效期 5 分钟，其后须再调用 ho_checkpoint(confirm=true)。');
-        out.push('如此设限的原因：压缩会丢弃历史，而参数由 AI 自行填写——惟有当前用户在设置页当面点击的那一次，方视为同意。');
+        out.push('交接已写好，但未排压缩：' + cs.reason + '。');
+        out.push('授权方式（任选其一）：① 在聊天框发送 /allow-compact（仅授权本会话，最为快捷）；② 在设置页的 dsh-handover 中点击「授权压缩」一次。授权有效期 5 分钟，逾期须重新授权后再调用 ho_checkpoint(confirm=true)。');
+        out.push('限制原因：压缩会丢弃历史，而调用参数由 AI 自行填写；只有当前用户亲自点击的授权，才视为同意。');
         return { text: out.join(NL) };
       }
-      // 成本提示：低于交接线强行压缩会白付一次摘要，且本轮前缀缓存失效。
+      // 成本提示：低于可压缩线强行压缩会多付一次摘要，且本轮前缀缓存失效。
       const handoverRatio = (env.cfg && env.cfg.handoverRatio) || 0.35;
       if (ratio !== null && ratio < handoverRatio) {
-        out.push('注意成本：当前水位 ' + (Math.round(ratio * 1000) / 10) + '% 低于交接线 ' + Math.round(handoverRatio * 100) + '% —— 属于提前压缩，会白付一次摘要调用，且本轮前缀缓存失效。');
+        out.push('成本提示：当前水位 ' + (Math.round(ratio * 1000) / 10) + '% 低于可压缩线 ' + Math.round(handoverRatio * 100) + '%，属提前压缩，会多付一次摘要调用，且本轮前缀缓存失效。');
       }
       consumedConsent(meId);
+      // 压缩后第一轮的水位读数是压缩前的旧投影，跳过那一轮提醒判定，免得用虚高读数用掉一次性提醒。
+      markSkipNext(meId);
       const n = count.used + 1;
       const resume = args.resume === 'wait' ? 'wait' : 'continue';
       env.schedule(meId, n, { resume });
-      out.push('当前用户已授权（' + cs.atText + ' 点击，剩 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
-      out.push("已登记压缩（第 " + n + "/" + env.cfg.maxCompactions + " 次）。本回合结束后执行。");
+      out.push('当前用户已授权（' + cs.atText + ' 点击，剩余 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
+      out.push("已登记压缩（第 " + n + "/" + env.cfg.maxCompactions + " 次），本回合结束后执行。");
       if (resume === 'wait') {
-        out.push("去向：wait —— 压缩完成后不会唤醒本会话，等你派新任务。");
+        out.push("去向：wait —— 压缩完成后不唤醒本会话，等待当前用户派新任务。");
       } else {
-        out.push("去向：continue —— 压缩完成后自动收到续跑消息；若 60 秒内没有续跑消息，用 ho_status 看状态。");
+        out.push("去向：continue —— 压缩完成后自动收到续跑消息；若 60 秒内未收到续跑消息，用 ho_status 查看状态。");
       }
-      out.push("压缩期间不要结束会话。");
+      out.push("压缩期间不得结束会话。");
       return { text: out.join(NL) };
     },
   };

package/src/tools/ho_docmap.mjs

@@ -1,10 +1,10 @@
 /**
- * ho_docmap —— 本会话的文档定位 map（只指路，不规定读多少）。
+ * ho_docmap —— 体系注册与文档定位（1.0）。
  *
- * 写入范围由会话已登记的角色决定，不接受传入项目名或任务名：全局只写 global.md，
- * 项目只写 project-<本项目>.md，杂项只写 misc-<本任务>.md。
+ * 动作：read 读、write 写、check 校验路径、plan 读写与归档行动计划。
+ * 写入范围由会话已登记的角色决定：全局只写总注册，项目只写本项目注册，杂项只写本任务注册。
  * 写入者必须是在任会话（以 Office.json 为准）；已交出的旧会话只读。
- * 不设字数上限；写盘前逐条校验路径存在，缺项整条拒绝并列出。
+ * 写入后重装本会话提示段，实现热更新。
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,11 +13,14 @@ import { nameOf } from '../lib/names.mjs';
 import { NL } from '../lib/text.mjs';
 import { loadOffice, lineageKeyOf } from '../lib/office.mjs';
 import {
-  lineageOf, lineageLabel, docmapRelPath, docmapAbsPath, readDocmap,
-  renderDocmap, validateEntries,
-} from '../lib/docmap.mjs';
+  lineageOf, lineageLabel, registryRelPath, registryAbsPath, readRegistry, readGlobalRegistry,
+  validateEntries, checkRegistries, writeRegistry, syncGlobalRefs,
+  planRelPath, readPlan, writePlan, archivePlan, pointRegistryToPlan,
+  GLOBAL_REGISTRY_REL, REGISTRY_NAME,
+} from '../lib/system.mjs';
+import { taskNameOk } from '../lib/role.mjs';
 
-export const ACTIONS = ['read', 'write', 'check'];
+export const ACTIONS = ['read', 'write', 'check', 'plan'];
 
 function ownLineage(env, exec) {
   let info = null;
@@ -38,15 +41,29 @@ function holderOf(ws, lin) {
 }
 
 function entriesText(entries) {
-  if (!entries.length) return '（空 map：不注入提示段）';
+  if (!entries.length) return '（空：不注入正文）';
   return entries.map((e) => '- ' + e.path + (e.about ? ' —— ' + e.about : '') + (e.when ? '（' + e.when + '）' : '')).join(NL);
 }
 
+function targetInfoFor(info, task) {
+  if (info && info.role === 'global') {
+    const t = String(task || '').trim();
+    if (!t) return null;
+    if (!taskNameOk(t)) throw new Error('任务名不合法（当目录名用）：' + t);
+    return { role: 'global-task', task: t };
+  }
+  return info;
+}
+
+function nodePath(ws, ...parts) {
+  return path.join(String(ws || ''), ...parts);
+}
+
 export function pmDocmapTool(env) {
   return {
     name: nameOf('docmap'),
     description:
-      '本会话的文档定位：action=read 读、write 写（逐条校验路径存在）、check 查自己的 map；只指路，不规定读多少。',
+      '体系注册与文档定位：read 读、write 写（逐条校验路径存在）、check 校验、plan 读写并归档行动计划；全局总注册只列路径，全局任务用 task 读写自身注册与计划。',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -54,99 +71,168 @@ export function pmDocmapTool(env) {
         action: { type: 'string', enum: ACTIONS, description: '缺省 read' },
         entries: {
           type: 'array',
-          description: 'write：整份替换。每项 { path: 工作区相对路径, about: 一句话介绍, when: 何时读 }',
+          description: 'write：整份替换。每项 { path: 工作区相对路径, about: 用途, when: 读取时机, section: structure|files }；section 缺省 files',
           items: {
             type: 'object',
             additionalProperties: false,
             required: ['path', 'about'],
             properties: {
               path: { type: 'string', description: '工作区相对路径，必须存在' },
-              about: { type: 'string', description: '一句话介绍' },
-              when: { type: 'string', description: '什么时候该读（可选，建议写）' },
+              about: { type: 'string', description: '用途，一句话' },
+              when: { type: 'string', description: '读取时机（可选）' },
+              section: { type: 'string', enum: ['structure', 'files'], description: '目录结构或规范文件（缺省 files）' },
             },
           },
         },
+        mode: { type: 'string', enum: ['read', 'write', 'archive'], description: 'action=plan 时的动作，缺省 read' },
+        text: { type: 'string', description: 'action=plan、mode=write 时的行动计划正文' },
+        task: { type: 'string', description: '全局会话操作某个任务时给任务名（项目与杂项会话省略）' },
       },
     },
     output: textOutput(),
     async execute(args, exec) {
       const ws = env.resolveWs(exec);
       const { info, lin } = ownLineage(env, exec);
-      if (!lin) throw new Error('本会话没有角色：文档定位只对全局、项目、杂项会话开放');
+      if (!lin) throw new Error('本会话没有角色：体系注册只对全局、项目、杂项会话开放');
       const action = typeof args.action === 'string' && args.action ? args.action : 'read';
       if (ACTIONS.indexOf(action) === -1) throw new Error('action 只能是 ' + ACTIONS.join(' | ') + '（收到 ' + String(action) + '）');
-      const rel = docmapRelPath(info);
-      const abs = docmapAbsPath(ws, info);
       const label = lineageLabel(info);
+      const meId = String(env.selfId(exec) || '');
 
       if (action === 'read') {
-        const map = readDocmap(ws, info);
-        const out = [];
-        out.push('文档定位（' + label + '）  ' + rel);
-        out.push(map.exists ? '状态  已设置，' + map.entries.length + ' 条' : '状态  未设置（空 map 不注入提示段）');
-        if (map.entries.length) out.push('', entriesText(map.entries));
+        const taskName = String(args.task || '').trim();
+        if (lin.kind === 'global' && taskName) {
+          const target = targetInfoFor(info, taskName);
+          const reg = readRegistry(ws, target);
+          const rel = registryRelPath(target);
+          const out = ['体系注册（' + lineageLabel(target) + '）  ' + rel];
+          out.push(reg.exists ? '状态  已设置，目录 ' + reg.data.structure.length + ' 条、规范 ' + reg.data.files.length + ' 条' : '状态  未设置');
+          if (reg.data.plan) out.push('计划  ' + reg.data.plan);
+          if (reg.data.structure.length) out.push('', '目录结构：', entriesText(reg.data.structure));
+          if (reg.data.files.length) out.push('', '规范文件：', entriesText(reg.data.files));
+          return { text: out.join(NL) };
+        }
+        if (lin.kind === 'global') {
+          const g = readGlobalRegistry(ws);
+          const out = ['体系注册（全局）  ' + GLOBAL_REGISTRY_REL, g.rows.length ? '任务 ' + g.rows.length + ' 个' : '暂无任务注册'];
+          for (const r of g.rows) out.push('  ' + r.kind + '「' + r.task + '」  ' + r.path);
+          return { text: out.join(NL) };
+        }
+        const reg = readRegistry(ws, info);
+        const rel = registryRelPath(info);
+        const out = ['体系注册（' + label + '）  ' + rel];
+        out.push(reg.exists ? '状态  已设置，目录 ' + reg.data.structure.length + ' 条、规范 ' + reg.data.files.length + ' 条' : '状态  未设置（空注册只注入一句提示）');
+        if (reg.data.plan) out.push('计划  ' + reg.data.plan);
+        if (reg.data.structure.length) out.push('', '目录结构：', entriesText(reg.data.structure));
+        if (reg.data.files.length) out.push('', '规范文件：', entriesText(reg.data.files));
         return { text: out.join(NL) };
       }
 
       if (action === 'check') {
-        const map = readDocmap(ws, info);
-        const bad = validateEntries(ws, map.entries);
-        const out = [];
-        out.push('文档定位体检（' + label + '）  ' + rel);
-        out.push(map.exists ? '条目 ' + map.entries.length + ' 条' : '未设置（空 map 不注入）');
-        for (const b of bad) out.push('  失效：' + b.path + ' —— ' + b.problem);
-        out.push(bad.length ? '判定：' + bad.length + ' 条失效，请更新 map。' : '判定：路径全部存在。');
+        const res = lin.kind === 'global' ? checkRegistries(ws) : checkRegistries(ws, info);
+        const out = ['体系注册体检  ' + (lin.kind === 'global' ? '全部任务' : label)];
+        if (!res.rows.length) out.push('  尚无任何任务注册（空注册不注入正文，属正常）');
+        for (const r of res.rows) {
+          out.push('  ' + r.label + '  ' + r.rel + '  ' + (r.exists ? r.entries + ' 条' : '未设置') + '  ' + (r.bad.length ? '失效 ' + r.bad.length + ' 条' : '路径全部存在'));
+          for (const b of r.bad.slice(0, 5)) out.push('        失效：' + b.path + ' —— ' + b.problem);
+        }
+        out.push(res.missing ? '判定：' + res.missing + ' 条路径失效，由该类别在任会话用 ho_docmap(action="write") 更新。' : '判定：路径全部存在。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'plan') {
+        const mode = typeof args.mode === 'string' && args.mode ? args.mode : 'read';
+        let target = null;
+        try { target = targetInfoFor(info, args.task); } catch (e) { throw e; }
+        if (!target) throw new Error('全局会话读写计划时须给 task（任务名）');
+        const rel = planRelPath(ws, target);
+        if (!rel) throw new Error('没有可用的计划路径：角色未定');
+        if (mode === 'read') {
+          const p = readPlan(ws, target);
+          if (!p.exists) return { text: '计划未建立：' + rel + NL + '层二任务应先写行动计划，模板见 _Control_Center/templates/Plan.skeleton.md。' };
+          if (p.error) throw new Error(p.error);
+          return { text: p.text };
+        }
+        if (mode === 'archive') {
+          const archived = archivePlan(ws, target);
+          return { text: archived ? '旧计划已归档：' + archived : '没有可归档的旧计划：' + rel };
+        }
+        const text = String(args.text || '');
+        if (!text.trim()) throw new Error('mode=write 需要 text（行动计划正文）');
+        const r = writePlan(ws, target, text);
+        let pointed = false;
+        try { pointed = pointRegistryToPlan(ws, target); } catch { pointed = false; }
+        let refreshed = false;
+        try { refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+        const out = ['已写入计划 ' + r.rel + '（' + r.bytes + ' B）' + (r.archived ? '；旧计划已归档 ' + r.archived : '；无旧计划')];
+        out.push(pointed ? '注册已指向该计划。' : '本任务尚无体系注册，写入注册后再指向计划。');
+        out.push(refreshed ? '提示段已重装。' : '提示段未能当场重装：下一轮或重启后生效。');
         return { text: out.join(NL) };
       }
 
       // action=write
       const holder = holderOf(ws, lin);
-      const meId = String(env.selfId(exec) || '');
       if (!holder.current) {
-        throw new Error('登记表里没有「' + (holder.key || label) + '」的在任记录：以在任记录为写入依据，先由全局完成登记');
+        throw new Error('名册里没有「' + (holder.key || label) + '」的在任记录：以在任记录为写入依据，先完成名称注册（ho_office action="register"）');
       }
       if (!meId || String(holder.current.sessionId || '') !== meId) {
         throw new Error('只有在任会话可以写：本条登记的在任会话为 ' + (holder.current.name || '?') + '（' + holder.current.sessionId + '），本会话为只读');
       }
+
+      if (lin.kind === 'global' && !String(args.task || '').trim()) {
+        const g = syncGlobalRefs(ws);
+        let refreshed = false;
+        try { refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+        const out = ['已按磁盘任务重建全局总注册 ' + GLOBAL_REGISTRY_REL + '（' + g.rows.length + ' 个任务）'];
+        for (const r of g.rows) out.push('  ' + r.kind + '「' + r.task + '」  ' + r.path);
+        out.push(refreshed ? '提示段已重装：下一轮即注入引用清单。' : '提示段未能当场重装：重启 DSH 或让会话重建后生效。');
+        return { text: out.join(NL) };
+      }
+
+      // 全局任务：由全局会话直接维护该任务的体系注册。
+      const writeInfo = lin.kind === 'global'
+        ? targetInfoFor(info, String(args.task || '').trim())
+        : info;
+      if (!writeInfo) throw new Error('全局会话写任务注册时需要 task（任务名）');
       const list = Array.isArray(args.entries) ? args.entries : null;
-      if (!list) throw new Error('write 需要 entries 数组（每项 path、about、when）');
-      const entries = [];
+      if (!list) throw new Error('write 需要 entries 数组（每项 path、about、when、section）');
+      const structure = [];
+      const files = [];
       for (const raw of list) {
         const e = raw || {};
         const p = String(e.path === undefined || e.path === null ? '' : e.path).trim();
         const about = String(e.about === undefined || e.about === null ? '' : e.about).trim();
         const when = String(e.when === undefined || e.when === null ? '' : e.when).trim();
+        const section = e.section === 'structure' ? 'structure' : 'files';
         if (!p) throw new Error('entries 里有空路径');
         for (const [field, val] of [['path', p], ['about', about], ['when', when]]) {
           if (val.indexOf('|') !== -1) throw new Error(field + ' 里不能出现竖线「|」（表格分隔符）：' + val);
           if (val.indexOf(String.fromCharCode(10)) !== -1) throw new Error(field + ' 里不能换行');
         }
-        entries.push({ path: p, about, when });
+        (section === 'structure' ? structure : files).push({ path: p, about, when });
       }
-      const bad = validateEntries(ws, entries);
+      const bad = validateEntries(ws, structure.concat(files));
       if (bad.length) {
         const lines = ['未写入：下列路径不存在或不合法，逐条修正后重试。'];
         for (const b of bad) lines.push('  - ' + b.path + '：' + b.problem);
-        lines.push('路径一律写工作区相对路径（例：Projects/<项目>/SKILL.md）。');
+        lines.push('路径一律写工作区相对路径（例：Projects/<项目>/README.md）。');
         throw new Error(lines.join(NL));
       }
-      fs.mkdirSync(path.dirname(abs), { recursive: true });
-      let backup = '';
-      if (fs.existsSync(abs)) {
-        backup = abs + '.bak';
-        try { fs.copyFileSync(abs, backup); } catch { backup = ''; }
+      const cur = readRegistry(ws, writeInfo);
+      const plan = cur.data.plan || '';
+      if (plan) {
+        const problem = validateEntries(ws, [{ path: plan }]);
+        if (problem.length) throw new Error('注册里的计划路径已失效：' + plan + NL + '先修正计划（ho_docmap action="plan"）或删除该行。');
       }
-      const body = renderDocmap(info, entries);
-      const tmp = abs + '.tmp-' + process.pid;
-      fs.writeFileSync(tmp, body, 'utf8');
-      fs.renameSync(tmp, abs);
+      const r = writeRegistry(ws, writeInfo, { structure, files, plan });
+      if (lin.kind === 'global') syncGlobalRefs(ws);
       let refreshed = false;
-      try { if (typeof env.refreshPromptFor === 'function') refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+      try { refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
       const out = [];
-      out.push('已写入 ' + rel + '（' + entries.length + ' 条）' + (backup ? '；原文件备份为 ' + path.basename(backup) : ''));
-      out.push(refreshed ? '提示段已重装：下一轮即按新 map 注入。' : '提示段未能在本进程重装：重启 DSH 或让会话重建后生效。');
-      out.push('建议精炼：每条一句介绍、一句时机即可；不设字数上限，但太长的介绍会挤占提示段。');
-      if (!entries.length) out.push('空 map：不注入提示段（相当于撤销）。');
+      out.push('已写入 ' + registryRelPath(writeInfo) + '（目录 ' + structure.length + ' 条、规范 ' + files.length + ' 条）'
+        + (r.backup ? '；原文件备份为 ' + path.basename(r.backup) : ''));
+      out.push(refreshed ? '提示段已重装：下一轮即按新注册注入。' : '提示段未能当场重装：重启 DSH 或让会话重建后生效。');
+      out.push('只给路径与用途；不设字数上限，但过长的用途会挤占提示段。');
       return { text: out.join(NL) };
     },
   };

package/src/tools/ho_gate.mjs

@@ -6,6 +6,7 @@ import { textOutput } from '../lib/output.mjs';
 import { NL } from '../lib/text.mjs';
 import { syncCheck, renderSyncCheck, docmapReport, renderDocmapCheck } from '../lib/gates.mjs';
 import { lintGlobal, lintProject, renderLintGlobal, renderLintProject } from '../lib/lint.mjs';
+import { legacyInfo } from '../lib/legacy.mjs';
 import { SETUP_STEPS } from '../lib/guide.mjs';
 
 function lintAllProjects(ws) {
@@ -26,12 +27,12 @@ export function pmGateTool(env) {
   return {
     name: nameOf('gate'),
     description:
-      '通用约束条闸门（按库型判定）＋交接文档体检。只读。',
+      '通用约束条闸门（按库型判定）、交接文档体检与体系注册路径检查。只读。',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
-        scope: { type: 'string', enum: ['all', 'global', 'project'], description: '默认 all' },
+        scope: { type: 'string', enum: ['all', 'global', 'project'], description: '缺省 all' },
         project: { type: 'string', description: 'scope=project 时的项目名' },
       },
     },
@@ -47,16 +48,20 @@ export function pmGateTool(env) {
         const g = syncCheck(ws);
         if (g.noWorkspace) {
           out.push('通用约束条闸门：未接入工作区（' + g.path + '）');
-          out.push('把工作区接入就好，一共四步：');
+          out.push('接入工作区共 4 步：');
           SETUP_STEPS.forEach((s, i) => out.push('  ' + (i + 1) + '. ' + s));
           return { text: out.join(NL) };
         }
         out.push(renderSyncCheck(g).join(NL));
         out.push(renderLintProject(null, lintAllProjects(ws)).join(NL));
         out.push(renderDocmapCheck(docmapReport(ws)).join(NL));
+        try {
+          const legacy = legacyInfo(ws);
+          if (legacy.exists) out.push('旧文档定位待迁移：' + legacy.dir + '（ho_workspace action="migrate"）');
+        } catch { /* 旧目录检查失败不影响闸门 */ }
       } else if (scope === "project") {
         const name = args.project;
-        if (!name) throw new Error("scope=project 时必须给 project 参数");
+        if (!name) throw new Error("scope=project 时须给 project 参数");
         const f = path.join(ws, "_Project_Meta", name, "Handover.md");
         out.push(renderLintProject(name, [{ name, file: f, res: lintProject(f) }]).join(NL));
       }