kld-sdd 2.7.8-2 → 2.7.8-4

package/README.md

@@ -4,6 +4,8 @@ KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语
 
 本分支已调整使用方式：模式与测试策略自动选择，按已有授权连续处理，KB 断连时继续本地工作，发布时核对真实基线。新规则、设计依据与尚未完成的结构调整见 [使用摩擦分析](USABILITY.md)。旧安装副本需要更新后才会应用这些规则。
 
+日常提交默认只保留本地关联 Hook；Apply 自动执行代码/Spec 检查、真实测试与交付验证。旧项目升级、备份回退、多仓和 CI 边界见 [Git Hook 调整说明](USABILITY.md#2026-09-10git-hook-收缩与交付验证)。
+
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

package/USABILITY.md

@@ -102,3 +102,55 @@ SDD 应帮助团队留下三类东西：明确的业务约定、能够证明实
 本机独立后端联调确认七种 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 位说明。