Finish Project

Finish Project —— 项目收尾：回写 → 归档

> 框架不可变铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7 条） > 本 SKILL.md 及其 scripts/ / tests/ 等框架文件在"使用本 skill"过程中只读。 > 发现 bug 必须立刻停下，向用户报告，由用户决定是否开新会话修。 > 唯一豁免：用户在当前会话明确声明"现在就是来改这个 skill 的"。

> Finish Git 铁律 > finish-project 全流程禁止执行 git push。 > 禁止自动 merge dev / master / main 分支，禁止生成或执行把需求分支合入这些主干分支的命令。 > 如需上线合并，只能在收尾报告中提示“请人工按团队流程处理”，不得由本 skill 代办。

职责边界

finish-project 只做项目完结收口：

1. 审计 workspace// 的 PRD/TRD/Plan/STATUS/TDD/Review 证据。
2. AIWeave 整合后（仅 Go 项目，aiweave_status in {T1, T2}）：

• 跑最终 /sync-feature-to-docs（vendor skill）：输入 = git diff（项目分支 vs main）+ TRD docs_increment_plan + context.json.pending_docs_sync_notes（developer 阶段累计的任务 build_status_module_path / build_status_target）+ vendor 模板路径；主 Agent 按 vendor templates/skills/sync-feature-to-docs/SKILL.md 执行；反向同步 docs/、新增所有 developer 阶段新建模块的 ⬜ 行并翻 🟢、更新 INDEX。这是 TRD bootstrap 之后唯一合法的 docs/BUILD_STATUS.md 写入窗口。产物 /finish_aiweave_sync_report.md。
• 跑 /doc-sync-check all 兜底：无 blocking 才继续；有 blocking → 写入 FINISH_REPORT 并停下。
• 派发 finish-project-reviewer 评审目标改为 docs/ 同步 diff（不再走 KB 回写候选评审）。

1. 把一次性项目产物移动到 archive//。
2. 把 *.review_report.json、*.hard_check_report.json、*.dev_review_report.json、finish_aiweave_sync_report.md 移入 review-history/。
3. 生成 FINISH_REPORT.md 留痕，新增「AIWeave 同步状态」段：本次同步 docs/ 文件清单、BUILD_STATUS 变更、未通过 doc-sync-check 项。
4. 生成本地任务分支清理计划，并在用户明确确认时只删除安全的本地任务分支。

> 强制归档场景（用户选「跳过 AIWeave 同步」）：FINISH_REPORT 显著标红「AIWeave docs/ 未同步，下次需先手工补齐」；context.json 写 aiweave_sync_skipped=true。

> 断开旧 KB 回写：旧版"KB 回写候选 + 用户三选一"流程已废弃。原 collect_kb_candidates / dispatch_kb_reviewer / apply_kb_writeback / auto_converge_kb_candidates 调用节点不再触发；脚本残留路径保持向后兼容旧 archive 但不在新流程中走通。

不做：

• 不自动 commit / push，尤其禁止 git push。
• 不自动 merge dev / master / main。
• 不自动删除远端分支。
• 不删除需求总分支、当前分支、dev / master / main / docker。
• 不移动 knowledge/ 目录本身。
• 不替用户确认 KB 回写项。

---

标准流程

入口来源可以是启动页 4、自然语言“归档项目 / 项目收尾 / finish project”、developer 完成后的衔接，或 继续项目 / 下一步 识别出的 finish_ready。无论从哪里进入，后续都由本状态机统一接管项目选择、收尾审计、KB 回写确认和归档确认。

Step 1 · 选择项目

运行：

python3 skills/finish-project/scripts/finish_wizard.py

状态机返回 action="ask_user" 时，把 presentation.question 原文给用户，等待用户回复编号。禁止在入口层自行扫描并包装项目状态。

全局返回入口词（与 AGENTS.md 一致）：用户本条输入仅为 nexus 或 Agent（单独一行；大小写不敏感）时，不得视为无效选项、不得要求用户「请重新回复 1」；主 Agent 立即退出 finish-project 追问，重新展示 1–6 启动入口，不把该字符串传入 finish_wizard.py 的 selection / confirm_text 等参数。用户在新入口重新选流程后，再按路由进入对应 skill。

Step 2 · 收尾审计

用户选择项目后调用：

python3 skills/finish-project/scripts/finish_wizard.py \
  --params-json '{"selection":""}'

状态机审计：

• context.json 是否存在。
• prd_path / trd_path / plan_dir 是否存在。
• plans/**/STATUS.md 任务是否全部 completed。
• TDD Audit 是否全部 red / green / refactor 为 true。
• 阻塞项是否清空。
• review 报告数量。

收尾确认菜单遵循单一选项原则（2026-05-11 起）：所有状态都只展示 1 个正向选项，下面再用一句话提示"不想现在归档，请结束会话。"。不再展示 cancel 编号选项——cancel 等价于"用户什么都不做就退出"，用自然语言/直接结束会话表达即可；保留显式 cancel 反而误导用户以为另有别的归档路径。

| 项目状态 | 唯一选项 | Agent 翻译契约 | |---|---|---| | can_finish=true（无阻塞） | 1. 确认归档 | 用户回复 1 → confirmed=true 再调；全局词 nexus / Agent（单独一行）→ 退出本 skill 并展示入口；用户表达不想归档（或回复其他非全局词内容） → 直接结束本次 finish 会话，不再调脚本 | | can_finish=false（有阻塞） | 1. 强制归档（带未完成项归档，FINISHREPORT 中注明） | 用户回复 1 → confirm_text="强制确认"（明确授权强制归档，等价 force=True）；全局词 nexus / Agent（单独一行）→ 退出本 skill 并展示入口；其余非全局词 → 结束会话 | | 仅缺人工确认（pendingconfirm 场景 A） | 1. 确认归档（系统自动补登 ✅ completed） | 同 canfinish=true | | 真未完成项 + 缺人工确认（pendingconfirm 场景 B） | 1. 强制归档 | 同 can_finish=false |

底层 archive_project.py 仍执行硬闸：未完成项目调用必须带 --force --force-confirm 强制确认，否则拒绝移动目录。Agent 拿到 wizard 返回的 execution_plan 后调 archive_project.py 时，若该项目 can_finish=false，必须显式补 --force --force-confirm 强制确认。

Step 3 · 生成 KB 回写候选并批量质检

确认进入收尾后，状态机会执行：

python3 skills/finish-project/scripts/collect_kb_candidates.py \
  --workspace-path 

候选只能从当前项目的 TRD 与 Plan 中提取；不得从 PRD、review 报告、历史聊天或 Agent 自己总结中凑候选。候选按 TRD/Plan 知识点生成，每个 Cxxx 是一个已通过初筛、值得让用户判断是否回写的知识单元，而不是一句简单摘要或原始候选。状态机会对每个知识点遍历 context.json.knowledge_base_dirs / kb_paths 中的所有依赖 KB，并为每个 KB 给出 append_targets / kb_evaluations：

| 目标文件 | 候选来源 | |---|---| | 01-architecture.md | 业务目标、范围、系统边界、版本关系、权限/中间件、主链路不变性 | | 02-database.md | MySQL/ES 表结构、字段、索引、Redis Key 模板本体、存储模型 | | 03-api.md | HTTP Path、请求字段、响应字段、错误码、接口协议、字段来源 | | 04-business-logic.md | 列表/创建/提交/排行等业务流程、状态流转、清理/结算链路 | | 05-dependencies.md | 配置中心、Redis/MQ/ES/HTTP 下游、缓存 TTL、资源读写边界、账期依赖 | | 06-code-conventions.md | 常量命名、目录约定、测试约束、实现规范、迁移注意事项 |

候选生成、finish-project-reviewer 和本地 hard gate 必须共用同一套 TRD/Plan 语义映射规则。禁止候选生成用一套关键词、reviewer 再用另一套口径，导致类似“业务目标写入 03-api.md”“配置中心/Redis 依赖写入架构章”这类前后漂移。当前共享规则落在 skills/finish-project/scripts/kb_writeback_mapping.py，主要约束是：

• “业务目标 / 范围 / 系统边界 / 版本关系 / 权限中间件 / 主链路不变性”默认归 01-architecture.md；若同一段明确描述配置中心、Redis、MQ、ES、下游或读写边界，则资源事实优先归 05-dependencies.md。
• “HTTP Path / 请求响应字段 / 错误码 / 接口协议”才归 03-api.md；不能因为文本里出现“路由”“请求”就把业务目标或依赖策略写入接口章。
• 建议追加正文必须是稳定 KB 差量正文，不能直接复制 TRD 原段；hard gate 对原文照搬、过长正文、reviewer 流水、候选 Cxxx、截断尾句执行 major 拦截并给出 rewrite。

候选生成后，不得直接展示给用户。必须先批量派发 reviewer：

python3 skills/finish-project/scripts/dispatch_kb_reviewer.py \
  --workspace-path  \
  --candidates-path /finish_kb_candidates.raw.json \
  --round 1

宿主有 subagent 能力时，必须使用派发包里的 task_prompt_template 启动独立上下文 finish-project-reviewer。Cursor 可用 generalPurpose + task_prompt_template，仍算真 sub-agent；Claude Code / OpenCode 使用注册的 finish-project-reviewer。

reviewer 派发不可停规则（对齐 developer）

收到 finish_wizard.py 返回 action="dispatch_reviewer" 后，这是主 Agent 的内部下一步，不是给用户看的阶段性结果：

• Cursor 中必须立即调用 Subagent(subagent_type="generalPurpose", prompt=task_prompt_template)，默认同步等待完成；禁止主动后台派发来换取提前回复。
• reviewer 未落盘期间，禁止输出“请等 Agent 跑完 / 看到 JSON 后告诉我 / 回到本会话发 reviewer 好了”等用户操作项。
• reviewer 完成后，主 Agent 必须读取 reviewer_output_path，确认 JSON 合法、dispatch_id 匹配，再把 candidates_path、reviewer_report_path、review_round 回传 finish_wizard.py。
• reviewer 报告通过后，finish_wizard.py 会生成 finish_kb_candidates.reviewed.json 并进入逐项 Cxxx 展示。
• reviewer 报告有 blocking/major 时，主 Agent 必须按报告修复候选并重派，最多 3 轮；禁止让用户手工执行 repair / redispatch。
• 只有 Subagent 工具不可用、报告未落盘且重派仍失败、或修复需要业务判断时，才允许停下给用户选项。

最终回复前可运行：

python3 skills/finish-project/scripts/finish_flow_guard.py \
  --wizard-result-path 

can_stop=false 时禁止向用户收口，必须按 required_action 继续内部流程。

reviewer 一次性审完整批候选 C001-C00N，而不是每个候选派一次。若 reviewer 报告有 blocking / major，主 Agent 先用报告修复候选，再重新派发 reviewer；最多 3 轮。最终：

• reviewer 通过：只展示通过版本。
• 修完后条目数可能不变，也可能从 15 条变成 10 条。
• 连续 3 轮仍未清理干净：停止自动循环，把当前候选和 reviewer 未解决问题一起交给用户选择。

回流硬门禁：

• reviewer 返回后，不管 approved=true/false，主 Agent 都必须先把 candidate_decisions 应用到候选，完成 remove / retarget / rewrite / drop。
• 应用后必须运行本地 hard gate（run_kb_candidate_review.py 同等规则）兜底检查错误 KB、错误章节、整段 TRD 原文、过程编号、重复追加正文。
• 只有 reviewer approved 且 hard gate 无 blocking/major，才允许写出 finish_kb_candidates.reviewed.json 并展示给用户。
• reviewer approved 但 hard gate 发现 major，仍必须先自动修复并重派 reviewer；禁止把“用户逐条择优选择”作为质量问题的替代修复。

无 subagent 能力的宿主才可降级运行：

python3 skills/finish-project/scripts/auto_converge_kb_candidates.py \
  --workspace-path  \
  --max-rounds 3

降级模式必须在汇报中标明；它只能作为机械兜底，不替代语义 reviewer。

向用户展示候选项时必须逐项推进，默认不写回，禁止先展示完整候选大表后让用户批量选择，禁止只给“跳过 / 写指定编号 / 写全部”的粗菜单后让用户自行判断。允许在第 1 条前展示一个轻量“候选概览”（总数 + Cxxx 标题 + 推荐目标），但概览只用于让用户知道全貌，不能提供批量写回选项；随后必须立即进入 C001 的详细确认。

collect_kb_candidates.py 只有在知识点通过以下初筛后，才允许分配 Cxxx 编号：

• 不是 TRD 过程信息、文档执行约束、guard/lint 规则、模板字段补齐等噪音。
• 至少命中一个依赖 KB 的合法章节，并存在推荐追加目标。
• 具备以下价值之一：新增事实、修正旧事实、补齐缺失细节、提升可开发性、沉淀跨项目复用经验、既有系统再梳理价值。
• 即使本次代码未实现，只要内容基于现有代码 / 现有 KB / TRD+Plan 对既有系统的详细梳理，且比 KB 更可开发，也可进入候选；但必须标明实现状态与可信度来源。

每个 Cxxx 至少展示：

• TRD/Plan 原文摘录（trd_excerpt / content）。
• 来源文件与来源类型（TRD / Plan）。
• 实现状态：已实现需说明代码证据；未验证或强制归档时标注“未验证 / 仅来自 TRD 或 Plan”。
• 为什么值得回写（worthiness.reason）、价值类型（worthiness.value_type）与命中的价值信号。
• 对每个依赖 KB 的判断：目标 KB、目标章节、建议动作、理由。
• 建议追加文本。
• 建议追加文本必须是最终将写入 KB 的正文；不得包含 候选 Cxxx、reviewer 轮次、dispatch id、reviewer_output_path 等过程信息。

标准交互是一次只展示一个 Cxxx：

1. 若当前是第 1 条，可先展示轻量候选概览：共有 N 条、每条标题、推荐写入目标数或目标章节。
2. 来源确认：说明来自 TRD 还是 Plan，展示来源文件。
3. 内容摘录：展示 TRD/Plan 原文摘录。
4. 原因说明：说明为什么值得回写。
5. 目标确认：列出只来自 append_targets 的目标 KB/章节；非 append 的 KB 只能作为“不建议写入”原因。
6. 用户选择：1. 同意回写 / 2. 不回写，继续下一条 / 3. 暂停。
7. 处理完当前 Cxxx 后，才展示下一个 Cxxx。

展示层硬约束：

• 只能展示脚本返回的 append_targets 作为可写入目标；禁止根据 knowledge_base_dirs 手工合成 C001-K01 / C001-K02。
• kb_evaluations 中 action != "append" 的目标只能展示为跳过原因，不能出现在“默认追加 / 推荐追加”里。
• 若某个 Cxxx 的 append_targets 为空，不得展示给用户确认，必须跳过该候选并继续下一个。
• 候选总览里的“主目标”必须来自 append_targets，不得写成“两 KB 同路径各一份”这类概括。
• 展示层必须清理目标理由里的跨域脏标签：如果最终只写某个 KB，理由不得保留其他非目标领域的标签。r 修复流水（如多段“reviewer 修正 / reviewer 改写追加正文”）原样暴露给用户；目标确认必须拆成“目标 KB / 目标章节 / 推荐理由 / 建议追加正文”四段，推荐理由只保留用户决策需要的信息。
• 建议追加正文不得以半句结尾（如“主从延迟下”“考虑”“避免”“按”等截断尾巴）；hard gate 必须拦截并重写。

用户确认粒度：

• 回复 C001：写入该知识点下所有推荐 append_targets。
• 回复 C001-K02：只写入该知识点的某个目标 KB。
• 回复“跳过 C001”：不得写回该知识点。
• 用户要求修改追加文本时，先按用户意见修改候选内容，再写回。

强制归档场景下，长期 KB 只应写入用户明确确认的项；未确认或未实现项可以记录到 FINISH_REPORT.md，不得默认写入 knowledge/。

Step 4 · 写回 KB

用户确认候选后运行：

python3 skills/finish-project/scripts/apply_kb_writeback.py \
  --workspace-path  \
  --candidates-json  \
  --confirmed-ids C001,C003-K02

写回前自动备份被修改 KB 文件到 .backup/finish-project//...。 写回脚本只允许目标位于本仓库 knowledge/ 下，且文件名必须属于 00-index.md ~ 06-code-conventions.md。 写回方式统一为追加式回写，不直接改写原有段落。

若用户选择“跳过 KB 回写”，不得写 knowledge/。

Step 5 · 归档项目

运行：

python3 skills/finish-project/scripts/archive_project.py \
  --workspace-path 

归档规则：

• workspace// → archive//
• review / hardcheck / devreview 报告 → archive//review-history/
• 归档目录生成 FINISH_REPORT.md
• workspace-path 必须是本仓库 workspace//，防止误移动任意目录

未完成项目如需强制归档，必须使用：

python3 skills/finish-project/scripts/archive_project.py \
  --workspace-path  \
  --force \
  --force-confirm 强制确认

Step 6 · 分支清理（交互式，由 finish_wizard 内建）

分支清理现在在归档执行前由 finish_wizard.py 交互式完成，无需手动运行脚本。

触发时机：finish_wizard.py 在返回 action=execute 之前，会自动检测业务仓库中的本地任务分支，若存在可安全删除的分支，则返回 stage=branch_cleanup_ask 向用户提问：

找到 N 个可安全删除的本地任务分支（已 completed 且已合入 ）：
- `feature/my-module-t01`（T01，...）
- `feature/my-module-t02`（T02，...）
...
注：需求总分支 `feature/my-module` 及 master/main/dev 等受保护分支不会被清理。

请选择：
1. 自动清理（删除以上任务分支）
2. 手动清理（自行处理后回复「我已清理」）
3. 跳过（保留所有分支不动）

处理规则：

• 用户选 1（自动清理）→ branch_cleanup_choice=auto，wizard 立即执行删除，结果写入 execution_plan.branch_cleanup.deleted；
• 用户选 2（手动清理）→ 等用户回复「我已清理」后 branch_cleanup_choice=manual，不执行任何 git 操作，继续归档；
• 用户选 3（跳过）→ branch_cleanup_choice=skip，直接进入归档。

安全约束：

• 只删 safe_to_delete（matched -tNN，已 completed 且已合入总分支的本地任务分支）；
• 需求总分支、基础分支、master / main / dev / docker 永远不删；
• 不 push，不删远端分支，不 merge 到 dev / master / main；
• 若待删任务分支恰好是当前 checkout 分支（最后任务收尾后的常见状态），branch_cleanup_plan.py 会标 requires_checkout_switch=True，并在执行删除前自动 git checkout 再删；删除完成后保持在集成分支上。前提是工作区干净：若有未提交改动，会拒绝切换并把该分支放进 skipped_delete，等用户先 commit / 丢弃后重试。

归档完成后，FINISH_REPORT.md 中的分支清理区块会反映清理结果（已删 / 保留 / 跳过）。

---

输出规范：决策点 Tips 追加

所有向用户展示含编号选项（1. / 2. / 3.）的消息，必须在选项列表末尾追加以下内容（禁止省略）：

---
💡 迷路了？输入「下一步」继续

适用场景：项目选择、KB 候选确认、归档确认、分支清理询问等所有带编号选项的节点。

---

交付格式

完成后简短汇报：

项目已归档：archive/

Review 历史：review-history/
收尾报告：archive//FINISH_REPORT.md

分支清理已在归档前通过 finish_wizard.py 交互式完成（见 Step 6），归档结束后无需再询问。

收尾换会话引导（归档完成后必须追加，禁止省略）

归档汇报是整条 finish 流程里上下文最满、用户又「不知道下一步」的节点。因此在上面汇报的正下方必须原样追加这一行（finish 不再依赖 Stop hook 上下文报警，无论上下文是否真满都给）：

本项目已归档完成。如需继续其它工作，请先 `/clear`，再输入 `nexus` 回到启动入口。

注意：这里是「项目已结束 → 回入口」，别用 developer 那套「/clear 后选 2. 继续进行中的项目」。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xurb-nexus
• Source: xurb-nexus/nexus-harness
• License: Apache-2.0
• Homepage: https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.