@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/spec/10-data-model.md

@@ -18,13 +18,29 @@
 | --- | --- | --- | --- | --- |
 | id | string | yes | 唯一标识 | system |
 
-## 存储边界
-
-- persistence_boundary：TBD
-- schema_or_migration_required：TBD
-- consistency_requirements：TBD
-
-## 禁止混入
+## 存储边界
+
+- persistence_boundary：TBD
+- schema_or_migration_required：TBD
+- consistency_requirements：TBD
+- transaction_sensitive_writes：TBD
+
+## 迁移与历史数据
+
+- migration_plan：TBD
+- historical_data_compatibility：TBD
+- backfill_or_seed_strategy：TBD
+- rollback_strategy：TBD
+
+## 数据变更检查清单
+
+- 是否允许直接改字段名 / 类型：
+- 是否需要 migration 文件：
+- 旧数据为空、默认值、回填和兼容窗口：
+- 索引 / 唯一约束 / 外键 / 租户隔离变化：
+- 哪些写路径必须事务化：
+
+## 禁止混入
 
 - 产品背景。
 - UI 行为。

package/package-source/docs/codex-harness-engineering/templates/spec/11-security-design.md

@@ -4,14 +4,22 @@
 
 定义认证、授权、输入校验、密钥处理、外部服务和威胁模型。
 
-## 安全边界
-
-| 边界 | 当前决策 | 说明 |
-| --- | --- | --- |
-| authentication | TBD | TBD |
-| authorization | TBD | TBD |
-| secret_management | env | 不写入仓库 |
-| input_validation | TBD | TBD |
+## 安全边界
+
+| 边界 | 当前决策 | 说明 |
+| --- | --- | --- |
+| authentication | TBD | TBD |
+| authorization | TBD | TBD |
+| secret_management | env | 不写入仓库 |
+| input_validation | TBD | TBD |
+
+至少补齐：
+
+- 后端权限校验入口，不能只写前端隐藏按钮
+- 资源所有权 / 租户隔离 / 角色边界
+- 输入校验范围：类型、长度、枚举、金额、日期、文件、特殊字符
+- 敏感信息返回、日志、trace、审计中的脱敏策略
+- 登录、注册、验证码、支付、领取、上传、搜索等高风险入口的限流 / 风控策略
 
 ## STRIDE 摘要
 
@@ -19,8 +27,17 @@
 | --- | --- | --- | --- |
 | Spoofing | TBD | TBD | 13 |
 
-## LLM / 外部服务注意事项
-
-- 不记录密钥、cookie、token。
-- 不把敏感输入写入 trace。
-- 外部调用必须有失败态证据。
+## LLM / 外部服务注意事项
+
+- 不记录密钥、cookie、token。
+- 不把敏感输入写入 trace。
+- 外部调用必须有失败态证据。
+
+## 安全控制清单
+
+| 控制项 | 最低要求 | 验证方式 |
+| --- | --- | --- |
+| 权限校验 | 服务端强制校验角色、资源权限、本人 / 本租户 | API / integration / e2e |
+| 输入校验 | schema / validator 覆盖类型、长度、枚举、金额、日期、文件 | unit / api |
+| 敏感信息脱敏 | token、密码、手机号、身份证、密钥、堆栈不直接返回给用户或写入 trace | response + log review |
+| 防刷 / 风控 | 登录、注册、验证码、支付、上传等入口有频率限制或幂等控制 | integration / security test |

package/package-source/docs/codex-harness-engineering/templates/spec/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放默认 `docs/spec/*` 规格模板，是当前安装主线最直接的硬规格入口。
+
+## 结构索引
+
+- `01..14`：从来源、范围、PRD、用户故事、功能规格、架构、契约、数据模型到 RTM 的完整规格链。
+- `spec-manifest.json` / `spec-manifest.schema.json`：规格清单与结构约束。
+
+## 修改规则
+
+- 改这里要同时考虑 `spec-lint.ps1`、driver 的 spec gate、以及安装后项目 `docs/spec/*` 的可维护性。
+- 如果某些产品语义同时在 `product/` 和 `spec/` 重复，优先明确两者分工，不要继续无序叠加。

package/package-source/docs/codex-harness-engineering/templates/testing/ACCEPTANCE_CRITERIA.md

@@ -1,39 +1,39 @@
-# 验收标准
-
-**功能**:
-**最后更新**:
-**负责人**:
-
-## 规则
-
-- 每条 P0/P1 需求都必须有唯一的 Requirement ID。
-- 每条 P0/P1 需求都必须描述可观察的成功结果和失败结果。
-- 避免使用“体验良好”“足够快”“易于使用”这类没有可度量判定依据的模糊表述。
-
-## 模板
-
-### REQ-XXX-001 <需求标题>
-
-#### 用户目标
-
--
-
-#### 业务规则
-
--
-
-#### 可观察结果
-
--
-
-#### 负向 / 异常条件
-
--
-
-#### 测试层级
-
-- 单元:
-- 组件:
-- API / 契约:
-- 集成:
-- E2E / 视觉:
+# 验收标准
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+## 规则
+
+- 每条 P0/P1 需求都必须有唯一的 Requirement ID。
+- 每条 P0/P1 需求都必须描述可观察的成功结果和失败结果。
+- 避免使用“体验良好”“足够快”“易于使用”这类没有可度量判定依据的模糊表述。
+
+## 模板
+
+### REQ-XXX-001 <需求标题>
+
+#### 用户目标
+
+-
+
+#### 业务规则
+
+-
+
+#### 可观察结果
+
+-
+
+#### 负向 / 异常条件
+
+-
+
+#### 测试层级
+
+- 单元:
+- 组件:
+- API / 契约:
+- 集成:
+- E2E / 视觉:

package/package-source/docs/codex-harness-engineering/templates/testing/ACCEPTANCE_EXAMPLES.md

@@ -1,37 +1,37 @@
-# 验收示例
-
-**功能**:
-**最后更新**:
-**负责人**:
-
-## 模板
-
-### REQ-XXX-001 <需求标题>
-
-#### 正向示例
-
-给定
--
-
-当
--
-
-则
--
-
-#### 负向示例
-
-给定
--
-
-当
--
-
-则
--
-
-#### 证据目标
-
-- 测试文件:
-- 截图 / 日志:
-- 最终验证证据:
+# 验收示例
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+## 模板
+
+### REQ-XXX-001 <需求标题>
+
+#### 正向示例
+
+给定
+-
+
+当
+-
+
+则
+-
+
+#### 负向示例
+
+给定
+-
+
+当
+-
+
+则
+-
+
+#### 证据目标
+
+- 测试文件:
+- 截图 / 日志:
+- 最终验证证据:

package/package-source/docs/codex-harness-engineering/templates/testing/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放测试左移、追溯、测试数据、回归计划、验收报告和验证矩阵模板。
+
+## 结构索引
+
+- `ACCEPTANCE_*`：验收标准和示例。
+- `NATURAL_LANGUAGE_TEST_CASES.md`：自然语言用例。
+- `TRACEABILITY_MATRIX.md` / `verify-matrix.md`：追溯和验证矩阵。
+- `TEST_DATA_MATRIX.md` / `test-data-plan.md`：测试数据。
+- `REGRESSION_PLAN.md` / `RISK_BASED_TEST_PLAN.md`：回归和风险计划。
+- `test-report.md` / `failure-triage.md`：验收报告与失败归因。
+
+## 修改规则
+
+- 这里是“测试真相源模板”，不是测试代码目录。
+- 改动要检查与 `task-session-strategy.md`、driver 验证链路和对应 lint 脚本是否一致。

package/package-source/docs/codex-harness-engineering/templates/testing/EVIDENCE_PROTOCOL.md

@@ -1,48 +1,54 @@
-# 证据协议
-
-**功能 / 项目**:
-**最后更新**:
-**负责人**:
-
-## 必需证据
-
-- 执行过的命令
-- 退出码 / 结论
-- 适用时的截图或日志路径
-- 关联的 Requirement ID
-- 关联的测试文件
-
-## 测试证据包
-
-每个 P0/P1 测试用例或高风险回归至少应能回溯到下面证据:
-
-| 证据 | 适用场景 | 说明 |
-| --- | --- | --- |
-| natural_language_test_case | PRD 完成后、实现前 | 每条 P0/P1 需求的自然语言测试用例，包含 Requirement ID、PRD 来源、步骤、Oracle、数据、证据路径和 TDD RED 预期失败 |
-| tdd_red_log | `feature_impl`、bugfix、重构 | 测试先写且按预期失败；失败原因必须是目标行为缺失，而不是语法、导入、环境或测试数据错误 |
-| tdd_green_log | `feature_impl`、bugfix、重构 | 最小实现后复跑同一 focused test 并通过 |
-| tdd_refactor_log | `feature_impl`、bugfix、重构 | 重构后 affected tests、coverage、lint、类型检查或等价 guard 仍通过 |
-| request_response | API、E2E | 请求、响应、状态码、错误码、Trace ID |
-| db_snapshot_before_after | 写接口、状态流转、批处理 | 操作前后关键表 diff 和 unexpected diff 检查 |
-| cache_observation | 缓存、权限、多租户 | key、TTL、hit/miss、失效结果 |
-| event_log | 队列、事件、Webhook | 事件类型、payload、消费次数、失败重试 |
-| audit_log | 权限、删除、资金、审批 | actor、action、object、result |
-| screenshot_video_har | UI、E2E、视觉 | 截图、视频、HAR 或 Playwright trace |
-| coverage_or_trace | 白盒、集成、跨服务 | coverage 命中、日志命中或链路 trace |
-| failure_repro | 失败用例 | seed、账号、curl、初始状态、实际结果、疑似位置 |
-
-## 无副作用证据
-
-权限拒绝、非法状态流转、校验失败和重放攻击类用例必须证明没有产生业务副作用:
-
-- 目标业务数据未变化。
-- 不产生成功事件或重复事件。
-- 不写入错误缓存。
-- 不泄露目标资源敏感字段。
-- 必要时记录拒绝审计。
-
-## 新鲜度规则
-
-- 证据必须来自当前变更集。
-- 如复用了过期截图或日志，必须明确说明。
-- 最终 verify 只应汇总能够回溯到当前任务的证据。
+# 证据协议
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 必需证据
+
+- 执行过的命令
+- 退出码 / 结论
+- 适用时的截图或日志路径
+- 关联的 Requirement ID
+- 关联的测试文件
+
+## 测试证据包
+
+每个 P0/P1 测试用例或高风险回归至少应能回溯到下面证据:
+
+| 证据 | 适用场景 | 说明 |
+| --- | --- | --- |
+| natural_language_test_case | PRD 完成后、实现前 | 每条 P0/P1 需求的自然语言测试用例，包含 Requirement ID、PRD 来源、步骤、Oracle、数据、证据路径和 TDD RED 预期失败 |
+| tdd_red_log | `feature_impl`、bugfix、重构 | 测试先写且按预期失败；失败原因必须是目标行为缺失，而不是语法、导入、环境或测试数据错误 |
+| tdd_green_log | `feature_impl`、bugfix、重构 | 最小实现后复跑同一 focused test 并通过 |
+| tdd_refactor_log | `feature_impl`、bugfix、重构 | 重构后 affected tests、coverage、lint、类型检查或等价 guard 仍通过 |
+| request_response | API、E2E | 请求、响应、状态码、错误码、Trace ID |
+| db_snapshot_before_after | 写接口、状态流转、批处理 | 操作前后关键表 diff 和 unexpected diff 检查 |
+| cache_observation | 缓存、权限、多租户 | key、TTL、hit/miss、失效结果 |
+| state_source_snapshot | URL、store、form、本地状态 | 证明同一业务条件只有一个主状态来源 |
+| event_log | 队列、事件、Webhook | 事件类型、payload、消费次数、失败重试 |
+| audit_log | 权限、删除、资金、审批 | actor、action、object、result |
+| request_trace_sample | API、服务、网关 | 请求 ID、用户 ID、接口路径、耗时、错误原因 |
+| alert_evidence | 监控、告警、失败态 | 告警规则、阈值、通知通道、触发结果 |
+| validation_failure_sample | 输入校验、文件上传、非法枚举 | 无效输入、错误码、错误字段、无副作用结果 |
+| redaction_check | 响应、日志、trace、审计 | 敏感字段已脱敏或未落盘 |
+| rate_limit_observation | 登录、注册、验证码、支付、上传、搜索 | 限流命中、验证码、幂等、告警或拒绝结果 |
+| screenshot_video_har | UI、E2E、视觉 | 截图、视频、HAR 或 Playwright trace |
+| coverage_or_trace | 白盒、集成、跨服务 | coverage 命中、日志命中或链路 trace |
+| failure_repro | 失败用例 | seed、账号、curl、初始状态、实际结果、疑似位置 |
+
+## 无副作用证据
+
+权限拒绝、非法状态流转、校验失败和重放攻击类用例必须证明没有产生业务副作用:
+
+- 目标业务数据未变化。
+- 不产生成功事件或重复事件。
+- 不写入错误缓存。
+- 不泄露目标资源敏感字段。
+- 必要时记录拒绝审计。
+
+## 新鲜度规则
+
+- 证据必须来自当前变更集。
+- 如复用了过期截图或日志，必须明确说明。
+- 最终 verify 只应汇总能够回溯到当前任务的证据。

package/package-source/docs/codex-harness-engineering/templates/testing/NATURAL_LANGUAGE_TEST_CASES.md

@@ -9,10 +9,11 @@
 - 每条 PRD 需求必须先识别需求类型、优先级、风险因子，再按下方“需求类型覆盖矩阵”生成自然语言测试用例。
 - P0 需求默认不少于 5 条自然语言测试用例；P1 需求默认不少于 3 条；P2 需求可为 1-2 条，但必须说明不进入 TDD 候选的原因。
 - 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
-- 每条用例必须绑定 Requirement ID、PRD 来源、测试层级、测试数据、Oracle 和证据路径。
-- 写操作必须说明业务副作用；权限拒绝、非法状态、校验失败和重放请求必须说明无副作用证据。
-- TDD 候选用例必须写清 RED 预期失败，供 `qa_contract.tdd_contract.red` 消费。
-- 自然语言用例先于测试脚本和实现代码存在；缺失时不得进入 `feature_impl`。
+- 每条用例必须绑定 Requirement ID、PRD 来源、测试层级、测试数据、Oracle 和证据路径。
+- 写操作必须说明业务副作用；权限拒绝、非法状态、校验失败和重放请求必须说明无副作用证据。
+- TDD 候选用例必须写清 RED 预期失败，供 `qa_contract.tdd_contract.red` 消费。
+- 自然语言用例先于测试脚本和实现代码存在；缺失时不得进入 `feature_impl`。
+- 存在业务规则表时，每条高风险业务规则至少映射 1 条测试用例，不能只挂在 PRD 文本里不进测试。
 
 ## 需求类型覆盖矩阵
 

package/package-source/docs/codex-harness-engineering/templates/testing/REGRESSION_PLAN.md

@@ -1,20 +1,28 @@
-# 回归计划
-
-**功能 / 发布版本**:
-**最后更新**:
-**负责人**:
-
-## 受影响测试
-
--
-
-## P0 回归集合
-
--
-
-## 发布证据
-
-- verify 摘要:
-- 契约验证:
-- e2e smoke:
-- 视觉一致性:
+# 回归计划
+
+**功能 / 发布版本**:
+**最后更新**:
+**负责人**:
+
+## 受影响测试
+
+-
+
+## 影响面
+
+- 直接影响:
+- 间接影响:
+- 相关接口 / 契约:
+- 相关页面 / 路由:
+- 潜在风险:
+
+## P0 回归集合
+
+-
+
+## 发布证据
+
+- verify 摘要:
+- 契约验证:
+- e2e smoke:
+- 视觉一致性:

package/package-source/docs/codex-harness-engineering/templates/testing/RISK_BASED_TEST_PLAN.md

@@ -1,16 +1,16 @@
-# 基于风险的测试计划
-
-**功能**:
-**最后更新**:
-**负责人**:
-
-| 风险 ID | 需求 / 区域 | 高风险原因 | 测试重点 | 必需 Oracle | 负责人 | 证据路径 |
-| --- | --- | --- | --- | --- | --- | --- |
-| RISK-001 | | | | | | |
-
-## 规则
-
-- P0 主流程应在实现前识别阻塞性风险。
-- 安全、权限、支付、数据一致性和迁移路径需要明确的负向覆盖。
-- 权限、资金、删除、跨租户、状态机、幂等、并发和外部回调默认按高风险处理。
-- 高风险项必须说明成功态、失败态和无副作用证据。
+# 基于风险的测试计划
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+| 风险 ID | 需求 / 区域 | 高风险原因 | 测试重点 | 必需 Oracle | 负责人 | 证据路径 |
+| --- | --- | --- | --- | --- | --- | --- |
+| RISK-001 | | | | | | |
+
+## 规则
+
+- P0 主流程应在实现前识别阻塞性风险。
+- 安全、权限、支付、数据一致性和迁移路径需要明确的负向覆盖。
+- 权限、资金、删除、跨租户、状态机、幂等、并发和外部回调默认按高风险处理。
+- 高风险项必须说明成功态、失败态和无副作用证据。