kld-sdd 2.7.8 → 2.8.1

package/README.md

@@ -4,6 +4,32 @@ KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语
 
 本分支已调整使用方式：模式与测试策略自动选择，按已有授权连续处理，KB 断连时继续本地工作，发布时核对真实基线。新规则、设计依据与尚未完成的结构调整见 [使用摩擦分析](USABILITY.md)。旧安装副本需要更新后才会应用这些规则。
 
+日常提交默认只保留本地关联 Hook；Apply 自动执行代码/Spec 检查、真实测试与交付验证。旧项目升级、备份回退、多仓和 CI 边界见 [Git Hook 调整说明](USABILITY.md#2026-09-10git-hook-收缩与交付验证)。
+
+## 工具更新与卸载
+
+**更新不需要先卸载。** 在原工作目录重新运行安装器，覆盖运行脚本、Skills 和只读模板；Spec 文档、KB 绑定、项目身份、历史数据、用户配置和自定义 Hook 保留。先确认目标编辑器及 Spec 目录，完成后检查实际部署版本。下载失败不启动安装；执行中断后可以重跑补齐，不承诺整个项目的事务回滚。
+
+```bash
+# 选择包含本次修复的新发布版本，在原工作目录更新
+npx kld-sdd@<新版版本号> --tool=cursor --spec-path=team-sdd-specs --skip-openspec
+
+# 卸载只有工具一种方式；可以先看计划
+npx kld-sdd@<新版版本号> uninstall --dry-run
+npx kld-sdd@<新版版本号> uninstall
+```
+
+卸载不再提供全量删除，旧 `--purge` 参数会报错退出。`openspec/`（含活动变更、归档和规格）、KB 配置、身份、历史数据、`.sdd.yaml`、`.sdd-spec-root`、`.sdd-workspace.yaml`、Git 关联和隐私忽略规则始终保留。工具目录内的未知文件和自建规则也保留；Git Hook 只有完整匹配受管版本时才删除。预览后文件改变需要重新预览。
+
+多仓注意：
+
+- 升级沿用已有清单，只维护登记的代码仓；多个 Spec 和备份不会互相接入。新代码仓通过 `kld-sdd sync-repos` 明确接入，追加清单时保留注释、自定义字段和原有记录。
+- 本地路径、团队远程声明或工作区清单冲突时，先停止更新并提示核对，不自动换绑。
+- 从单个代码仓卸载时，工作目录外的共享 Spec 工具保留。从 worktree 卸载时，共用的 Git Hook 保留，应从主仓库管理。
+- 旧平铺 `skywalk-sdd/` 只清理已知工具，历史数据原位保留，不自动合并两份项目身份或运行状态。
+
+以上行为需要使用包含本次改动的新版本；修改此源码不会改变已经发布的 npm 包。安装包通过 `sddMaintenance.toolOnly: 1` 声明该维护契约，托盘据此避免用旧安装器处理存在已知清理风险的布局。
+
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

package/USABILITY.md

@@ -82,3 +82,75 @@ SDD 应帮助团队留下三类东西：明确的业务约定、能够证明实
 新增回归覆盖 Full/Simple 结果等价、正文增改删后的重新校验、跨 Change 身份冲突、strict profile、结束时重新解析、strict JSON 记录拒绝占位值，以及八种 Agent 的参考文件渲染。消费方需要重新安装/更新技能和 skywalk-sdd 运行时才能使用新参数；只更新技能文件会导致旧运行时缺少合并输出。
 
 验证结果（2026-09-08，本次 Check 优化）：完整 `npm test` 通过，包含新增 6 组 Check 回归与全部既有用例；`npm run bench:check` 的 7 轮结论与任务计数等价断言全部通过。
+
+## 2026-09-10：真实执行与故障恢复
+
+本次承接已发布的 `2.7.8-1`，继续提交在 `codex/sdd-usability`。以下新增能力尚未重新发布 npm；原有身份、入库协议、七种 Skill 使用上报保持兼容。
+
+- `kld-sdd log` 修正为实际打包的 `index.cjs` 入口。strict 记录失败会保留 details 文件，成功持久化后才清理。
+- `test-run` 执行真实命令，保存退出码、耗时、原始 stdout/stderr 及 SHA-256。当前自动识别 Node TAP/原生测试摘要；未识别的 runner 仍保存输出，标记计数未知，不能自动完成任务。
+- `test-run --completion-file` 为明确声明的任务关联实际测试事件并同步 checkbox。命令执行成功不等于业务覆盖充分，任务与测试的对应关系仍需评审核验；缺少测试、路径错误、超时不能记成有效 RED。
+- `check-record` 接收实际检查项与真实评审身份，自动计算分类统计、任务缺口和结果，可通过 `--end-event-id` 一次记录并结束。按预检 profile 重新核对正文和历史身份；变化时拒绝旧评审。结束阶段复用本次刚完成的校验，避免再跑一次同样的对账。
+- Archive 在启动归档阶段前运行 doctor；终态通知独立记为 `run_end`，旧 `stage_end + run_ended` 在计算时兼容归一化，避免虚增阶段或孤儿日志。通知保留，原始旧日志不改写。
+- 修复进程锁发布窗口：完整锁文件原子发布，其他进程不能把尚未写完的锁当作失效锁抢走。
+- 文档按实际业务决策与验收行为组织，不为填模板反复复制背景、堆空章节或按每个参数值拆一次任务。
+
+详细参数与示例在 [Apply 参考](templates/skills/kld-sdd/opsx-apply/reference.md) 和 [Check 指南](templates/skills/kld-sdd/opsx-check/SKILL.md)。新命令需要更新运行时和 Skills，旧 `record --strict` 仍可使用。
+
+验证：完整 `npm test` 通过；新增 19 个真实执行/恢复回归，涵盖测试输出篡改、零测试、超时、RED、任务关联、旧评审拒绝、单次最终复核、真实归档和六进程竞争。打包及初始化器均部署两个新模块，安装后的真实入口也有回归覆盖。预检基准七轮中位数由 294.6 ms 降至 156.3 ms，减少 46.9%；它仅测程序预检，不代表模型评审总耗时。
+
+本机独立后端联调确认七种 Skill 的使用事件均成功写入，断网事件保留并恢复补报，服务端统计为 8 次、覆盖 7 阶段。使用统计是独立的 usage 事件，不等于测试通过、归档完成或 Spec 已入库；当前服务端按提交次数计数，网络响应丢失后的重复提交不提供 exactly-once 保证。
+
+配置 Skill 与参考同步去除默认首目标、截短 UUID 和旧监控项目绑定步骤，修正 KB API 字段映射；切换查询目标不再引导改写团队项目身份，权限失败也不清空其他目标可能仍有效的密钥。
+
+## 2026-09-10：Git Hook 收缩与交付验证
+
+日常 commit 负责保存工作，Apply 收尾负责检查交付，Spec 入库负责发布知识。新安装只自动接入一个本地 `commit-msg`，它不请求 KB、不调用模型、不扫描整个工作区，也不重复执行文档 Check。
+
+| 场景 | 当前行为 |
+|---|---|
+| 本次明确指定 Change | `KLD_SDD_CHANGE` 支持逗号分隔的多个 Change，校验目录后写关联 |
+| 未显式指定 Change | 只复用能与暂存文件内容逐项匹配的检查关联；多个候选或没有证据时提示待关联 |
+| Spec 仓尚未提交 | 允许保存代码，不写旧 HEAD 冒充当前 `Spec-Revision` |
+| 独立 Spec 仓干净且远端关系匹配 | 写完整不可变 Spec SHA；单仓不写自指 Revision |
+| 路径失效、Node 缺失或关联脚本超时 | 本次提交继续，显示待关联，不表示交付检查通过 |
+| 实施收尾 | Agent 自动进行代码/Spec 检查、真实测试和 `delivery-check verify` |
+
+关联 worker 设置 1.5 秒超时上限。这个上限不是性能测试结果；用户自有 Hook 的耗时不受 SDD 控制。
+
+### 一个验证入口，四个内部步骤
+
+入口是 `<spec-root>/skywalk-sdd/git-hooks/delivery-check.cjs`。Apply 自动串联，用户不需要记忆四条命令：
+
+1. `prepare --project=<代码仓Git根> --change=<Change> --base=<实施前SHA>`：记录输入，返回本次需要检查的文件和是否可复用旧回执。
+2. `record-review --project=... --change=... --input=<检查JSON>`：收录实际检查结果；输入改变、漏覆盖、失败、未检查都会明确显示。
+3. `test --project=... --change=... --session-id=... --task-ids=... --command-file=<命令数组JSON>`：内部复用原 `test-run`，保留严格测试事件、命令退出码及原始输出。
+4. `verify --project=... --change=...`：判断当前快照的证据是否完整。`ready` 与 `pending` 分开，不把 KB 入库或合并状态混入测试结果。
+
+机器回执绑定代码仓身份、Spec 仓身份、明确 Change、代码和 Spec 内容、规则版本与配置。当前保守地纳入本仓依赖文件及全局规格；相同指纹可复用，变化后再定向取证。它尚未实现自动跨仓依赖图或逐规则的最小重查。mtime 不再作为内容一致的证据。UTF-8 文本统一 LF 以兼容 Git autocrlf，二进制和符号链接目标按原始字节检查。
+
+检查结果分别记录接口、业务、校验和错误处理；`pass` 需要证据，`na` 需要理由，`not_checked` 与 `fail` 都不能算通过。回执记录 Agent 做过的检查及其输入，不单靠模型自报置信度判断正确性。
+
+测试计数支持 Node TAP 与 Maven Surefire/Failsafe 的结果摘要；未知测试格式保留实际输出并显示待验证，不编造计数。只有无业务代码变更、四个维度都经检查判为不适用，且回执有明确测试不适用理由时，才允许 `testStatus=not_applicable`，不会显示“测试通过”。
+
+### 多仓与正式提交
+
+每个代码仓分别存回执，同一 Change 的多仓结果互不覆盖。Spec 可以先于代码完成并入库；“规格已发布”和“实现已验证”是两个状态。
+
+需要核对已提交代码时使用 `verify --scope=commit --ref=<目标提交> --base=<实施前提交>`；独立 Spec 仓额外提供 `--spec-ref=<完整Spec SHA>`。命令读取指定 Git 对象，可以验证非当前 HEAD，不会用工作区替代。冲突解决改变内容后需重新检查和测试。
+
+本次没有自动启用团队 CI。现有 CI 样例不等于已接入的合并门禁。团队接入时需要在受信任的执行环境生成或提供相应回执与原始测试日志；当前测试回执包含本地路径，复制到另一机器不能直接当作可移植的验证包。可以在目标 checkout 上重新执行同一入口。
+
+### 已有项目升级与回退
+
+重新运行安装器会更新运行时与 Skills，并迁移已识别的原版 SDD Hook。已退役或更新的 Hook 先备份到 Git 公共目录的 `kld-sdd-hook-backups/`；回退时把对应 `.bak` 复制回 hooks 同名路径并恢复执行权限。
+
+只含 marker 不足以证明文件受管：追加过用户逻辑、Hook 符号链接、修改过插件列表、显式旧门禁设置都会保留并提示。`core.hooksPath`（包括 Husky）交给现有管理器维护；安装器不会接管其目录。普通 worktree 使用 Git 解析出的公共 hooks 目录。`hooks.config` 保留用户内容，重新安装不重置选项。
+
+空目录首次安装声明正确的 mono 布局；此前生成的原样多仓占位配置可备份后自动迁移，真实团队配置不会被猜测改写。只有一个无效 `.git` 目录时明确提示 Hook 未安装，本地文档与运行时仍可部署。
+
+### 上报与知识链路的边界
+
+原 Skill 使用上报、严格测试事件和 KB 上传/查询 API 保留。默认移除旧 pre-commit 后，不再采集那条仅凭“本次提交有代码而没有文档”推断的 bypass 事件；这类旧统计与真实 Skill 使用量不能混为一谈。
+
+`kb-upload --validate-only` 在未连接 KB 时可做本地语义校验，并明确说明未验证权限、发布基线及入库状态；正式上传仍严格检查项目与目标配置，连接或身份异常不能伪装为入库成功。UUID 继续完整保存，仅修正帮助中残留的 8 位说明。