[Hooks RFC #679] Task Schema: HookContext payload schema 公开与版本化

[Cai-Tang-www]

父 RFC: #679

背景

sanitizeUserHookContext 已经在 executor 内部维护一份白名单 metadata key 集合(见 internal/runtime/hooks/executor.go 第 339 行起),但:

1. 这份 schema 没有外部文档,user/repo hook 作者只能读源码
2. 没有版本字段,字段增删会悄无声息地破坏外部 hook
3. P6 command kind 必须依赖这个 schema 作为 stdin 协议契约

目标

把 HookContext payload 从"私有约定"提升为"对外契约",提供机器可读 schema + 显式版本号 + 兼容策略。

范围

1. 在 internal/runtime/hooks 新增:
   • PayloadVersion = "1" 常量
   • PayloadSchema(point HookPoint) PayloadSchema 描述该点位 metadata 字段、类型、稳定性等级
   • 字段稳定性分级:stable / experimental / deprecated
2. 同步生成机器可读 schema 文件:
   • docs/reference/hook-payload.v1.json (JSON Schema) — 通过 go generate 由 Go 源码导出
3. sanitizeUserHookContext 的白名单 key 必须从 PayloadSchema 派生,不再维护两份
4. 在 docs/runtime-hooks-design.md 增加 "Payload Schema" 章节
5. 添加测试:
   • 任何在 PayloadSchema 中标记 stable 的字段,删除会引起测试失败
   • JSON Schema 文件与 Go 源码不同步 → 测试失败

验收

• internal/runtime/hooks/executor.go 不再有硬编码 metadata key 列表
• 生成的 hook-payload.v1.json 进入仓库
• payload 含 payload_version: \"1\" 字段,user/repo hook 可读
• 文档列出每个点位的 metadata 字段表

依赖

• 与 #Task-Command 并行,落地前需对齐 (command hook 的 stdin schema = 本任务输出)

兼容策略

• minor 升级:仅新增字段,version 保持 1
• breaking 变更:升级为 2,旧 hook 仍可读 1 视图(runtime 双发)

不在本任务范围

• 引入完整的 JSON Schema 验证库到 runtime(只导出 schema,不在 runtime 内做验证)