--- disable-model-invocation: false name: spec-end description: > 当一个完整 Spec 的计划、实现、测试阶段都已完成，且角色 spec-ender 进入阶段五收尾时使用： 收集角色经验、触发 exp-reflect、审查项目规范、询问归档，并完成提交、推送、创建 PR。 不要用于功能实现中途、测试未完成时，或 spec-update 的小迭代收尾。 --- # Spec End ## 运行契约 > 进入核心原则前先对齐这张表。它把本 Skill 当成一个有边界的循环单元：明确读什么、能动什么、怎么算完成、什么时候停、什么时候交还给人。 | 项 | 本 Skill 的约定 | |----|----------------| | 输入 | 当前 Spec 全部角色产物、`lead/team-context.md`（含 Git 元数据）、TeamLead 转回的各角色经验素材 | | 权限 | 写 `ender/end-report.html`、调用 exp-reflect 分流、归档目录、git commit/push/创建 PR（`autopilot` 下可自主执行这些可逆动作）；维护 AGENTS.md/rules 属永远门禁，任何模式下都必须先经用户确认；合并、改动远程默认分支不在本 Skill 权限内；force push **仅豁免**收尾时对自己刚推送的 Spec 分支做 amend（`git commit --amend` + `git push --force-with-lease`，让 PR URL 等收尾写回并入同一次提交），其余 force push 不在权限内 | | 验证 | 各阶段已完成、经验已分流沉淀、规范审查有结论；归档前必须在当前工作树上跑一次全量测试并观察输出（新鲜验证，引用历史测试结论、「刚才是绿的」都不算）；合并完成后必须在**合并结果**上再跑一次全量测试——合并可能引入语义冲突，两个分支各自绿不代表合并后绿；归档前当前分支等于 `git_branch`，且不等于远程默认分支（用 `git symbolic-ref refs/remotes/origin/HEAD` 读出，不假定分支名） | | 停止 | 收尾确认方式随模式（见核心原则 4）；两项永远门禁——合并分支、直接改动远程默认分支——任何模式下都必须停下等用户，`autopilot` 遇到时就地降级为门禁模式；丢弃改动、删除分支必须拿到用户键入的精确确认词才执行；force push 仅收尾 amend 场景豁免（对刚推送的 Spec 分支 `--amend` + `--force-with-lease`），其余 force push 仍是门禁并需精确确认词；用户选"暂不归档"则只产出报告即停止 | | 升级 | 阶段未真正完成、全量测试未绿、规范变更影响面大、或 Git 状态异常（分支不符、在远程默认分支上提交）时，停止并交回用户决策 | ## 核心原则 1. **多角色视角**：通过 TeamLead 收集各角色视角的经验素材，不只是 spec-ender 的独角戏 2. **分流沉淀**：调用 exp-reflect 按权重分流（重大经验 → exp-write，轻量 → Auto Memory） 3. **规范维护审查**：判断本次 Spec 是否产生需要长期遵守的项目规范，必要时更新 AGENTS.md 或 .agents/rules/ 4. **确认方式随模式**：`gated` 模式下归档、提交、推送、创建 PR 前都必须用当前运行环境的确认方式询问用户；`autopilot` 模式下可自主 push 工作分支并创建 PR（两者可逆，且 PR 本身就是给人审的入口），但合并分支、直接改动远程默认分支这两项是永远门禁，任何模式下都必须停下等人；force push 仅收尾 amend 场景豁免（对刚推送的 Spec 分支做 `git commit --amend` + `git push --force-with-lease`，这是让收尾只提交一次的既定动作），其余 force push 仍是门禁 5. **GitHub Flow 收尾**：先跑全量测试，绿了之后才出收尾菜单——测试还红着的时候不要问用户「要不要归档」；放行后调用 git-work 提交、推送当前 Spec 分支并创建 PR 6. **报告用 HTML，记忆用 Markdown**：`ender/end-report.html` 遵循 html-report 契约（`rk:*` meta + `.rk-meta` 双轨元信息、`rk-links` / `rk-backlinks` 双向关联、`data-rev` 修订标记）；`spec/context/experience/*.md`、`knowledge/*.md` 保持 Markdown 不变；账本 `.md` / `.html` 皆可 ## 工作流程 ### 步骤 1：接收任务与接力 AWR 会话 1. 执行 AWR 会话接力与上下文准备： ```bash # 自动接力上游 spec-reviewer 的会话并转移任务租约（Claim Transfer） AWR_CP=.agents/skills/scripts/rk-awr-checkpoint.sh; [ -f "$AWR_CP" ] || AWR_CP=scripts/rk-awr-checkpoint.sh bash "$AWR_CP" --work --agent spec-ender --digest "接力开工准备归档" --next-action "执行归档与结项门禁" # 绑定当前会话提取全景上下文 awr work prepare --session --response-view summary ``` 2. 从 TeamLead 的启动指令中获取： - 当前 Spec 的目录路径 - 确认所有阶段（计划/实现/测试）已完成 - 当前工作分支（应与 `lead/team-context.md` 的 `git_branch` 一致） - base 分支（用 `git symbolic-ref refs/remotes/origin/HEAD` 读远程默认分支，不要假定分支名；`lead/team-context.md` 的 `base_branch` 与之不符时以远程为准并向用户说明） ### 步骤 2：扫描 Spec 目录 读取当前 spec 目录下的所有角色产物： - `lead/team-context.md`：团队运行上下文（Markdown 运行账本） - `explorer/exploration-report.html`：探索阶段发现 - `writer/plan.html`：设计方案 - `tester/test-plan.html`：测试策略 - `executor/summary.html`：实现细节 - `tester/test-report.html`：测试过程和结果 - `reviewer/review.html` / `reviewer/update-xxx-review.html`：审查报告（如有） - `updater/update-xxx.html` / `updater/update-xxx-summary.html`：更新方案和总结（如有） - `debugger/debug-xxx.html` / `debugger/debug-xxx-fix.html`：问题和修复（如有） 同时读取 `lead/team-context.md` 的运行账本： - frontmatter 的 `git_branch` / `base_branch` / `pr_url` - 「决策记录」：本次所有实质取舍及理由——end-report 的「关键决策」小结直接来自此表，无需重新回忆；用 `rk-cal key` 承载 - 「问题闭环记录」：本次遇到并解决的 bug 与过程性问题，供 exp-reflect 分流沉淀 如果 `git_branch` 为空或为 `none`，说明本 Spec 没有使用 GitHub Flow 分支；收尾时仍可归档文档，但提交/PR 步骤需要先询问用户。 ### 步骤 3：通过 TeamLead 收集团队成员素材 向 TeamLead 请求恢复或转询相关角色，收集本次开发的经验素材： ```text 询问 spec-writer：本次撰写 writer/plan.html 时遇到的困难、踩过的坑、值得记录的发现？ 询问 spec-tester：本次测试过程中的发现、边界情况、改进建议？ 询问 spec-executor：本次实现过程中遇到的技术挑战、解决方案、值得复用的模式？ 询问 spec-debugger：本次调试的根因分析、修复思路、预防建议？（如有 debug 文档） 询问 spec-reviewer：本次审查中发现的完成度风险、测试缺口或规范建议？（如有 review 文档） ``` 等待 TeamLead 转回各角色回复，汇总讨论结果。若运行环境无法恢复角色线程，则基于当前 Spec 目录文档补足对应视角。 ### 步骤 4：调用 exp-reflect 分流沉淀 以当前 Spec 目录文档为素材（exp-reflect 会直接读取文档，无需手动整理素材），调用 `/exp-reflect` 并传递目录路径： ```bash /exp-reflect spec/当前任务目录路径 ``` exp-reflect 会根据经验的重要性分流： - 重大经验（解决了重要问题、有高复用价值）→ `exp-write` 写入正式经验文件 - 轻量知识（小技巧、上下文记忆）→ Auto Memory - 项目规范、项目偏好或规则变化 → 建议更新 `AGENTS.md` / `.agents/rules/`（这些文件保持 Markdown） ### 步骤 5：项目规范维护审查 归档前轻量审查本次 Spec 是否产生长期规则或长期项目偏好。`AGENTS.md` 保持入口清单定位；只在命中明确、长期有效的变化时更新，不为了“有动作”而改规范。 | 发现内容 | 维护位置 | |----------|----------| | 项目名称/一句话身份、核心技术栈摘要、AGENTS 路由或 import 变化 | `AGENTS.md` | | 启动/部署方式、开发流程细则、长期编码约定、安全规则、日志/审计要求、测试约束、目录/命名规范、产品/前端偏好 | `.agents/rules/*.md` | | 可复用操作流程（部署、发布、迁移等） | `.agents/skills/sop-xxx/SKILL.md` | | 项目架构、数据流、模块理解 | `spec/context/knowledge/`（保持 `.md`，被 exp-search 检索） | | 困境-策略、踩坑经验 | `spec/context/experience/`（保持 `.md`，被 exp-search 检索） | 审查问题： - 本次是否形成了以后都要遵守的编码/安全/测试/日志/审计规则？ - 本次是否改变了项目身份摘要、AGENTS 入口路由、目录结构、模块边界、启动或部署方式？ - 本次是否形成了长期产品体验、前端样式或协作偏好，需要写入 `.agents/rules/project-preferences.md` 或相关 rules？ - 本次是否暴露了反复出现的问题，需要写入 rules 防止复发？ - 本次是否形成了可机械复用的 SOP，应创建或更新 Skill？ 如需更新，先向用户说明将修改哪些规范文件，得到确认后再编辑。 ### 步骤 6：创建 ender/end-report.html 并按模式确认归档创建 PR 在当前 Spec 目录下创建 `ender/end-report.html`，按 html-report skill 的固定骨架承载： - `` 写全 `rk:*` meta（`rk:type=end-report`、`rk:spec-dir`、`rk:role=spec-ender`、`rk:created`、`rk:updated`、`rk:revision`、`rk:mode`、`rk:git-branch`、`rk:base-branch`、`rk:pr-url`、`rk:tags`），并用 `` 声明关联；`.rk-meta` 人可读镜像同样字段（含运行模式、基准分支与 PR） - `rk-verdict`（`is-pass` / `is-fail`）一句话给出本次 Spec 的完成结论 - **首屏与图**（机检强制最低图种）：结论块一句话给出本次 Spec 的完成结论；紧跟流程条（`rk-flow`：探索 → 设计 → 实现 → 测试 → 审查 → 收尾，每个阶段用 `is-done` / `is-current` / `is-muted` 如实标注），放在结论块之后、第一个正文章节结束之前。可选补 `rk-kpis`：测试数、PR 状态（来自实际输出）。 - **图与表分工**：阶段完成情况用 flow；全量测试命令/退出码/证据路径、角色产物清单、经验与规范维护结论、归档/提交/推送/PR 的放行状态用表格。未执行的阶段按事实标为未开始，不画成已完成；测试未通过时结论块用 `is-fail`。 - **开发者审核关注点**：全量测试是否为收尾时的新鲜运行（命令 + 退出码 + 日志位置）；各角色产物是否齐套且双向链接一致；经验沉淀/规范维护是做了还是明确无需；归档、提交、推送、PR 各自由哪种模式放行，永远门禁项是否单列。 - **篇幅**：按内容选择图，不按字数凑图；单段聚焦一个判断，建议 150 字以内便于扫读。产物路径、命令与测试证据用表格或代码保留，不因篇幅删减。画法见 `html-report/references/figures.md` - 写完按 html-report「结构机检」一节的命令运行 `check-report.js`，退出码为 0 才算完成 - 「修订历史」表固定 5 列（修订/日期/修改人/改了什么/原因），不新增列；后续补 PR URL 等修改时修订号 +1、追加修订历史行、正文用 `data-rev` 标记，不静默改写；「原因」列源于实质取舍时引用账本「决策记录」的决策编号（如 `按 D-003（…）`），纯笔误/措辞/补充直接写清，不编造编号 - 正文章节：完成状态、本轮全量测试的命令与退出码（新鲜验证证据）、已扫描的角色产物路径、经验沉淀结果或无需沉淀的说明、规范维护结果或无需维护的说明、归档/提交/推送/PR 的确认状态（写明按哪种模式放行）、待用户处理的永远门禁项（合并/默认分支改动；force push 仅收尾 amend 场景豁免） - 关键决策用 `rk-cal key` 小结（取自账本「决策记录」，只写结论与一句话理由并标注 `D-xxx`，决策过程正文不复制进报告），遗留风险用 `rk-cal risk`，需后续观察项用 `rk-cal warn` - 末尾「关联产物」拆两个 `h3`：「本报告引用」用 `
    ` + `data-rk-link` 列出全部角色产物（`.html`）与 `运行账本`、沉淀的经验/知识 `.md`；「引用本报告」用 `
      ` + `data-rk-backlink` 列出引用方；本报告新建的每条关联都要到对侧报告的 `rk-backlinks` 补反链，对侧未产出时先标注（待创建） 然后跑一次全量测试并观察输出。**测试全绿之后才出收尾菜单**——红着的时候先把它变绿或交回用户决策，不要问用户「要不要归档」。 **AWR 零缺口硬门禁（Zero-Gap Gate）**： 在提请归档前，执行 AWR 静态结构与组织状态完整性检查： - **Linux / macOS / Git Bash 环境**： ```bash if ! command -v awr >/dev/null 2>&1; then echo "⚠️ 未安装 awr 命令，跳过 AWR 结构缺口检查" elif ! inspect_out=$(awr intake inspect --json 2>/dev/null); then echo "❌ AWR 诊断命令执行失败，请检查 .awr/ 配置与源文件语法" exit 1 elif command -v python3 >/dev/null 2>&1; then if ! printf "%s" "$inspect_out" | python3 -c 'import sys, json try: data = json.load(sys.stdin) except Exception as e: sys.stderr.write(f"❌ 无法解析 AWR 诊断输出: {e}\n") sys.exit(1) org = data.get("organization") if not isinstance(org, dict): sys.stderr.write("❌ AWR 诊断响应缺少 organization 组织节点\n") sys.exit(1) all_gaps = org.get("gaps", []) # 过滤阻断性结构缺口（目标未关联、验收项缺失、状态机断裂等） # 白名单排除项： # 1. completion_not_checked（未传 --source-sha 时对历史已完成项的审计提示） # 2. intake_work_only / business_work_missing（项目初始仅有 INTAKE-001 时的脚手架组织提示） IGNORABLE_CODES = {"completion_not_checked", "intake_work_only", "business_work_missing"} blocking_gaps = [g for g in all_gaps if g.get("code") not in IGNORABLE_CODES] if len(blocking_gaps) > 0: for bg in blocking_gaps: code = bg.get("code", "unknown") target = bg.get("target", "-") detail = bg.get("detail", "") sys.stderr.write(f" - [{code}] {target}: {detail}\n") sys.exit(1) print("✅ AWR 结构缺口检查通过 (0 Blocking Gaps)")'; then exit 1 fi elif command -v jq >/dev/null 2>&1; then if ! printf "%s" "$inspect_out" | jq -e '.organization' >/dev/null 2>&1; then echo "❌ AWR 诊断响应缺少 organization 组织节点" exit 1 fi blocking_count=$(printf "%s" "$inspect_out" | jq -r '[.organization.gaps[]? | select(.code != "completion_not_checked" and .code != "intake_work_only" and .code != "business_work_missing")] | length' 2>/dev/null || echo "error") if [ "$blocking_count" = "error" ]; then echo "❌ 无法解析 AWR 诊断响应" exit 1 elif [ "$blocking_count" -gt 0 ]; then echo "❌ 存在 $blocking_count 个 AWR 阻塞性结构缺口，禁止结项归档！" exit 1 fi echo "✅ AWR 结构缺口检查通过 (0 Blocking Gaps)" else echo "❌ 门禁阻断: 系统未检测到 python3 或 jq 解析器，无法完成 AWR 结构缺口严格审计，拒绝归档！" exit 1 fi ``` - **Windows 原生 PowerShell 环境**： ```powershell if (-not (Get-Command awr -ErrorAction SilentlyContinue)) { Write-Host "⚠️ 未安装 awr 命令，跳过 AWR 结构缺口检查" -ForegroundColor Yellow } else { $errFile = [System.IO.Path]::GetTempFileName() $rawJson = & awr intake inspect --json 2>$errFile $rawErr = if (Test-Path $errFile) { Get-Content $errFile -Raw -ErrorAction SilentlyContinue } else { "" } Remove-Item -Force $errFile -ErrorAction SilentlyContinue if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($rawJson)) { Write-Host "❌ AWR 诊断命令执行失败，请检查 .awr/ 配置与源文件" -ForegroundColor Red if ($rawErr) { Write-Host "AWR 错误: $rawErr" -ForegroundColor Yellow } exit 1 } $inspect = $null try { $inspect = ($rawJson -join "`n") | ConvertFrom-Json } catch { } if (-not $inspect -or -not $inspect.organization) { Write-Host "❌ AWR 诊断响应解析失败或缺少 organization 节点" -ForegroundColor Red exit 1 } $allGaps = @($inspect.organization.gaps) $ignorable = @("completion_not_checked", "intake_work_only", "business_work_missing") $blockingGaps = @($allGaps | Where-Object { $ignorable -notcontains $_.code }) if ($blockingGaps.Count -gt 0) { Write-Host "❌ 存在 $($blockingGaps.Count) 个 AWR 阻塞性结构缺口，禁止结项归档！详情:" -ForegroundColor Red foreach ($bg in $blockingGaps) { Write-Host " - [$($bg.code)] $($bg.target): $($bg.detail)" -ForegroundColor Red } exit 1 } Write-Host "✅ AWR 结构缺口检查通过 (0 Blocking Gaps)" -ForegroundColor Green } ``` 若返回非 0 退出码，必须回退排查并闭环工作项的目标关联、验收准则或测试证据，严禁带缺口归档。 **报告契约与测试证据机检（Report Contract & Evidence Gate）**： 零缺口门禁只管 AWR 结构，不管产物形态。以下机检覆盖 html-report 契约与 tdd-discipline 证据三要素，与零缺口门禁同为归档前置硬门禁（依据 2026-09-22 四场景并发实测：tech 7/7 报告违约、debt 7/7 缺反链+11 处行内样式、3/4 场景证据缺退出码/时间戳；本仓历史交付物中亦有同类先例，如 20260917-1600 Spec 的 test-report 8 处行内样式、20260916-2200 tech Spec 全部报告缺 manifest 脚本——全部由此类机检捕获）。 范围声明：**本门禁只扫描本次收尾的 ``**，历史归档 Spec 的既有偏差不追溯、不阻断；修历史报告属另一件工作，不在本门禁职责内。另注意本门禁只能校验产物**形态**，无法识别事后补写的伪造证据行——产出时效约束（证据必须由测试运行自身产出、禁止手写补写）仍以 `spec-execute/references/tdd-discipline.md` 为准。 - **Linux / macOS / Git Bash 环境**： ```bash # 为本 Spec 物理目录，如 spec/versions/v0.1/specs/20260923-1000-feat-示例 if ! command -v python3 >/dev/null 2>&1; then echo "❌ 门禁阻断: 系统缺少 python3，无法执行报告契约机检，拒绝归档！" exit 1 fi if ! python3 - "" <<'PYEOF' import os, re, sys spec_dir = sys.argv[1] if not os.path.isdir(spec_dir): sys.stderr.write(f"❌ Spec 目录不存在: {spec_dir}\n"); sys.exit(1) violations = [] evidence_violations = 0 need_meta = ["rk:type","rk:version","rk:spec-dir","rk:category","rk:role","rk:mode", "rk:git-branch","rk:base-branch","rk:created","rk:updated","rk:revision","rk:pr-url"] need_cls = ["rk-verdict","rk-meta","rk-revs","rk-links","rk-backlinks"] CODE_SPAN = re.compile(r"(?s)
      .*?
      |.*?|`[^`\n]*`") def lineno(text, needle): i = text.find(needle) return text[:i].count("\n") + 1 if i >= 0 else 1 html_count = 0 for root, _, files in os.walk(spec_dir): for fn in sorted(files): if not fn.endswith(".html"): continue html_count += 1 p = os.path.join(root, fn) t = open(p, encoding="utf-8").read() depth = "../" * os.path.relpath(p, ".").count("/") for m in need_meta: if f'name="{m}"' not in t: violations.append(f"{p}:{lineno(t, '（ 内补齐，Spec 级报告必填）") for c in need_cls: if c not in t: violations.append(f"{p}:{lineno(t, ' ji): violations.append(f"{p}:{lineno(t, 'rk-report.js')}: rk-manifest.js 必须排在 rk-report.js 之前（defer 按文档序执行，反序则 file:// 导航树为空）") # 行内样式/禁 fetch 检查前先剔除 
      //行内反引号内容：报告在代码引用里讨论这些模式（如修复 HTML 契约的 Spec）是合规叙述，不算违规
        t_visible = CODE_SPAN.sub("", t)
        if 'style="' in t_visible or re.search(r"]", t_visible):
            violations.append(f"{p}:{lineno(t_visible, 'style=')}: 禁止行内样式/