wrapup

默认在已有结构内完成必要记录和联动，不例行整理全项目。用户明确要求文档整理时，才读取 文档整理细则，按其中的目的与范围提出整理计划，复用本流程确认、执行与提交；有日常工作要收尾时，先完成日常提交，再整理并单独提交。没有要求整理时，看到可以整理的地方只在报告末尾提出(见第 5 节)，不扩大本次维护范围。

1. 收集变化

遵守当前任务授权、只读和禁改路径。机制运行规则 一致性机制/运行规则.md 不在当前上下文时先读取；按需读取 PROJECT 的信息归属和项目联动目录。

回看当前仍可见的对话，找已确认但未写入文件的内容：决策应已在 PROJECT.md「待提交」区，漏写的列入计划补写；其他约定按归属补写。纯讨论和未确认的想法不写成有效要求；用户要求保留的备选按备选记录。没有原始对话的信息不凭空恢复。

机械步骤由随附脚本负责，这些结果只由脚本产生：检查范围与基线(scope.mjs)、决策迁出与「最近决策」、提交说明与提交(decisions.mjs)、并行的开工、同步主线、并进主线与收工(task.mjs)、synced 的创建与推进(synced-guard.mjs)。直接用脚本输出的值，不自己抄写哈希、另算基线或数行数；不手工代做这些步骤，也不手改脚本生成的内容，要改就带新选项重跑。不清楚用法时运行 node <脚本> --help，它只打印用法、不做任何改动。

脚本异常时先暂停受影响的操作，查明是未能运行、执行中断，还是检查发现了真实风险。未能运行时，按已有授权尝试恢复运行条件；检查发现风险时先解决问题，不手工绕过。执行中断或结果不明时，先只读核对实际文件与 Git 状态，尤其提交是否已经发生；确认已完成的步骤和可安全重试的范围后，再恢复脚本执行，不盲目重跑。

暂时无法恢复时，可以在授权范围内继续把有价值的信息和成果写入原有文件，保留待提交决策；不手改脚本生成内容，不替代脚本迁出决策、提交、合并或推进 synced。报告中区分“已写入文件”和“已提交”，说明失败、未完成步骤及状态不明之处，不把部分落盘说成收尾完成。

用一个脚本取得全部范围，输出为 JSON：

node .agents/skills/wrapup/scripts/scope.mjs

base 之后的 commits_since_base、committed_since_base(已提交的文件)与 worktree(暂存、未暂存、未跟踪)就是本次检查范围，不限于本次会话自己的编辑；其中可能有别人的工作，检查不等于有权修改或提交。已提交的文件只检查联动，不列入本次提交；拟提交的只有 worktree 中的改动与本次维护新改的文件。

未跟踪文件必须检查，按档读取：本次会话建的或改过的不重读；来历不明的先看脚本给的 head(开头 3 行)与行数；仍认不出且文件小才读全文；大文件、二进制与整个未跟踪目录不读全文，列出名称、大小与示例，交用户决定纳入提交、先不管或加入 .gitignore。

canonical 未配置时，先请用户确认，再写 projectConsistency.canonicalBranch 并重新运行脚本。没有可靠基线时不猜范围，可以维护资料，但不能声称范围检查完整；canonical 上还没有 synced 时，按工作区状态检查，并说明历史未设基线。PROJECT 或联动目录缺失时，报告缺口并提出最小补救，不自动安装或重组项目。

并行的三条与同步、并进主线的做法见运行规则第四节。task.mjs 另有：用户要求开并行时 start，要求收工时 close(删除前请用户先关掉该 worktree 里的会话)；各子命令的输出写明下一步(next)。

2. 拟定一份计划

对范围内每项变化，按项目联动规则检查受影响的资料：scope.mjs 的 linkage.rules_hit 列出本次范围按路径命中的规则，逐条读规则原文判断要改什么，rules_not_checked 中的规则自行判断；中枢清单用来判断是否受影响，不必全文读所有中枢。处理已发现的直接依赖，不开放式审计全库；查联动时优先搜索相关路径，减少无关输出。明确的依赖还没检查的，要么完成，要么报告为缺口。

把对话补写、正文更新、引用修正与必要联动合成一份计划，说明改哪里、改什么、为什么。优先用已有的维护位置；要求、实际成果、验证范围分开写。不为凑记录刷新日期；原始证据不改写，必要的替代原因就近写明。素材清单、二进制等特定检查只按项目自己的规则和本次变化触发。找不到落点或归属冲突时，提出最小调整。

决策：迁出前看一眼「待提交」，同一话题的几条合并成一条，几个不相干话题挤在一条里的拆开，颗粒度按运行规则；改写后的原文随计划给用户看。「待提交」区有决策且要迁出时(在主线上，或并进主线时加 --land)，先运行

node .agents/skills/wrapup/scripts/decisions.mjs plan

脚本按位置读取「待提交」，给出要迁出的决策、提交正文(body)与「最近决策」的变化(迁出后条数 recent_count_after、删除的行)。输出有 next 时按它处理，带上选项重跑 plan，直到没有 next。计划中写明迁出后条数与删除的行。

在非 canonical 分支上(不并进主线时)不迁出决策，也不必运行 plan：决策留在「待提交」随提交带走，这次提交就是任务检查点。之后可能由别的会话接手、或任务还没做完时，apply 加 --goal(整个任务，不是本次会话的范围)、--progress(做到哪里)、--remaining(这个任务还有什么没做，做完写「无」；不写提交、合并这类收尾动作)；没给的行沿用上一个检查点。一次提交就做完的小改动可以不加。

3. 一次确认

在非 canonical 分支上(包括并进主线时的合并版 wrapup)跳过本节：不展示、不等确认，直接执行并提交，报告照常。

默认只确认一次。一起展示：

• 维护计划：改哪里、改什么、为什么；
• 实际拟提交的文件清单，每个文件用文字标明状态(已修改、新建未跟踪、已删除等)，不贴 git 状态代号；标出计划外的文件；本次会话之前就存在的未提交改动注明来历，不说成本次所做；
• 提交说明全文，原样贴出，不能只给标题或概述：自写的标题(末尾带脚本给的 title_tag；提交时没写的话脚本会补上)与可选说明段，后接脚本给的 body；
• synced 能否推进及条件。

用户一句确认即执行维护、提交，并在条件满足时推进 synced；同一事项已有明确授权则沿用，不重复询问。以下情况要补充确认：实际拟提交范围超出计划(如混有其他工作的改动)、执行中计划改变、新增实质改动、超范围或授权冲突。用户确认时追加要求(如“再记一条决策”)也算计划改变：新增或改写的决策原文会进入提交正文，先展示再确认。只要求保存不提交时，确认的只是维护计划，到报告为止。

4. 执行与提交

按批准范围局部更新，改完读取相关正文或实际 diff，核对直接引用、必要联动和事实类别。不借收尾修改业务或重跑大型实验；业务没做完但记录准确，可以收尾。

执行后实际改动与确认时不一致(文件清单或提交说明需实质改变)时，先补确认。按批准的路径暂存，只有明确批准整个工作区时才可 git add -A；检查实际暂存内容与授权一致，保留已有暂存内容；混有其他工作、无法分离时停下，不擅自提交或重置。没有新改动不制造空提交。

提交一律由脚本完成，有无决策、是否在分支上都一样：其余维护完成、按批准路径暂存后运行 decisions.mjs apply --commit，选项与确认时的 plan 相同，并用 --title 传入标题(必须给；主线上用确认过的那个)、--intro 传入说明段(可选；分支上另按上文加三个选项)；宿主要求的额外 trailer(如 Co-Authored-By)用 --trailer "键: 值" 传入。脚本写好提交说明、暂存它改动的 PROJECT(分支上它不改 PROJECT)、提交并核对，bash、PowerShell 写法相同：

node .agents/skills/wrapup/scripts/decisions.mjs apply --commit --title "<确认过的标题>" [其他选项]

输出中 committed 为 false 时提交失败，立即停止后续 Git 动作；check.ok 为 false 时，列入“必要但未完成”。

以下条件全部满足才推进 synced，否则只提交、不推进(必要维护失败时，经用户明确同意可以先提交部分成果)：

• 在 canonical 分支上(分支上的提交只是检查点；并进主线时由 task.mjs land --finish 推进 synced)；
• 基线可靠，检查范围没有遗漏；
• “必要但未完成”为空，必要维护都在将标记的提交里；
• 用户授权成立；
• 工作区干净，重新 inspect 允许推进(首次创建 synced 也一样)。

node .agents/skills/wrapup/scripts/synced-guard.mjs inspect
node .agents/skills/wrapup/scripts/synced-guard.mjs advance

can_advance 只证明 Git 条件，不证明内容维护完成。未经用户要求不合并分支，不 push。

5. 报告

固定使用以下格式，没有的项写“无”。每项维护结果归入一类：完成；跳过(只用于已存在或无需改动的项)；失败(读取或写入失败不算成功)；必要但未完成(必要的改动因禁改、未授权或执行失败没做，不算跳过)。

wrapup 结果
- ✅ 已完成:<各项>
- ⏭️ 跳过:<仅限已存在或无需改动的项>
- ❌ 失败:<各项、原因与建议>
- ⚠️ 必要但未完成:<必要改动因禁改、未授权或失败而没做的各项及原因>
- ❓ 未核对范围 / 联动目录未覆盖:<各项>
- 📌 提交:<短 hash 或未提交>;synced:<已推进 / 未推进及原因 / branch checkpoint>
- 业务遗留:<各项>

“必要但未完成”不为空时，不得写“维护完成”；它不为空本身就阻止推进 synced，📌 行不必重复其中各项。

收尾过程中顺带注意到文档可以整理的地方(不准确、不好找、重复或过碎，见整理细则的目的)，或 scope.mjs 输出了 hints(大量重复的行、没有被任何文档引用的文档)并判断值得一提时，在报告末尾加“可以整理的地方”，列 1–3 条并各用一句话说明，问用户是否接着整理；不为此另行扫描，没有就不写。无需维护则直接说明。