@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/spec/05-user-stories-and-acceptance.md

@@ -0,0 +1,25 @@
+# 05 用户故事与验收标准
+
+## 职责
+
+把 PRD 场景拆成可验证的用户故事、需求 ID 和验收标准。本文是行为真源。
+
+## 用户故事
+
+| REQ ID | 用户故事 | 优先级 | 来源 | 状态 |
+| --- | --- | --- | --- | --- |
+| REQ-001 | 作为用户，我希望 TBD，以便 TBD。 | P0 | SC-001 | draft |
+
+## 验收标准
+
+### REQ-001
+
+| AC ID | Given | When | Then | 可自动化 |
+| --- | --- | --- | --- | --- |
+| AC-001 | TBD | TBD | TBD | yes |
+
+## 变更规则
+
+- 新增 P0/P1 REQ 时必须同步 13 和 14。
+- 修改行为时必须检查 06、09、10 是否受影响。
+- 不写 UI 像素、API 字段或存储实现。

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

@@ -0,0 +1,33 @@
+# 06 功能规格说明 FSD
+
+## 职责
+
+描述页面、状态、交互、错误展示和前端行为。本文是前端行为真源。
+
+## 页面与模块
+
+| 模块 ID | 名称 | 关联 REQ | 状态 |
+| --- | --- | --- | --- |
+| FSD-001 | TBD | REQ-001 | draft |
+
+## 状态与交互
+
+### FSD-001
+
+- 默认状态：TBD
+- 加载状态：TBD
+- 成功状态：TBD
+- 空状态：TBD
+- 错误状态：TBD
+
+## 对齐表
+
+| REQ ID | FSD 章节 | API 引用 | 测试引用 |
+| --- | --- | --- | --- |
+| REQ-001 | FSD-001 | 09 | 13 |
+
+## 禁止混入
+
+- 后端实现细节。
+- 数据库字段真源。
+- 测试用例全文。

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

@@ -0,0 +1,29 @@
+# 07 非功能需求与约束 NFR
+
+## 职责
+
+定义性能、安全、降级、可观测性、兼容性和可靠性底线。
+
+## 非功能需求
+
+| NFR ID | 类型 | 约束 | 优先级 | 验证方式 |
+| --- | --- | --- | --- | --- |
+| NFR-001 | performance | TBD | P0 | 13 |
+
+## 降级策略
+
+| 场景 | 降级行为 | 用户可见结果 | 证据 |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD |
+
+## 可观测性
+
+- 日志：TBD
+- 指标：TBD
+- Trace：TBD
+
+## 安全底线
+
+- 输入限制：TBD
+- 敏感信息处理：TBD
+- 权限边界：TBD

package/package-source/docs/codex-harness-engineering/templates/spec/08-architecture-design.md

@@ -0,0 +1,31 @@
+# 08 系统架构与技术选型
+
+## 职责
+
+说明系统分层、部署形态、关键技术选择和集成边界。机器可执行架构约束以 `docs/architecture/constraints.md` 为准，本文只引用并解释。
+
+## 架构约束引用
+
+- 约束包：`docs/architecture/constraints.md`
+- Stage 1 Review 必须读取该约束包。
+
+## 系统形态
+
+| 项 | 决策 |
+| --- | --- |
+| delivery_shape | TBD |
+| runtime_model | TBD |
+| deployment_unit | TBD |
+| production_entrypoints | TBD |
+
+## 分层设计
+
+| 层 | 职责 | 边界 |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## 关键决策
+
+| 决策 ID | 决策 | 原因 | 替代方案 |
+| --- | --- | --- | --- |
+| ADR-001 | TBD | TBD | TBD |

package/package-source/docs/codex-harness-engineering/templates/spec/09-api-contract.md

@@ -0,0 +1,37 @@
+# 09 API 接口规格
+
+## 职责
+
+定义对外行为契约。API 路径、请求字段、响应字段和错误体以本文为准。
+
+## 契约范围
+
+| API ID | 方法 | 路径 | 关联 REQ | 状态 |
+| --- | --- | --- | --- | --- |
+| API-001 | GET | /tbd | REQ-001 | draft |
+
+## API-001
+
+### Request
+
+```json
+{}
+```
+
+### Response
+
+```json
+{}
+```
+
+### Errors
+
+| code | HTTP | 含义 | 展示引用 |
+| --- | --- | --- | --- |
+| TBD | 400 | TBD | 06 |
+
+## 禁止混入
+
+- UI 布局。
+- 数据库内部结构。
+- 测试策略正文。

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

@@ -0,0 +1,31 @@
+# 10 数据模型与存储规格
+
+## 职责
+
+定义数据实体、字段、存储边界和迁移要求。数据字段以本文为准。
+
+## 实体
+
+| Entity | 说明 | 存储位置 | 关联 API |
+| --- | --- | --- | --- |
+| EntityTBD | TBD | TBD | API-001 |
+
+## 字段
+
+### EntityTBD
+
+| 字段 | 类型 | 必填 | 说明 | 来源 |
+| --- | --- | --- | --- | --- |
+| id | string | yes | 唯一标识 | system |
+
+## 存储边界
+
+- persistence_boundary：TBD
+- schema_or_migration_required：TBD
+- consistency_requirements：TBD
+
+## 禁止混入
+
+- 产品背景。
+- UI 行为。
+- 测试用例全文。

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

@@ -0,0 +1,26 @@
+# 11 安全设计规格
+
+## 职责
+
+定义认证、授权、输入校验、密钥处理、外部服务和威胁模型。
+
+## 安全边界
+
+| 边界 | 当前决策 | 说明 |
+| --- | --- | --- |
+| authentication | TBD | TBD |
+| authorization | TBD | TBD |
+| secret_management | env | 不写入仓库 |
+| input_validation | TBD | TBD |
+
+## STRIDE 摘要
+
+| 类型 | 风险 | 缓解 | 验证 |
+| --- | --- | --- | --- |
+| Spoofing | TBD | TBD | 13 |
+
+## LLM / 外部服务注意事项
+
+- 不记录密钥、cookie、token。
+- 不把敏感输入写入 trace。
+- 外部调用必须有失败态证据。

package/package-source/docs/codex-harness-engineering/templates/spec/12-implementation-plan.md

@@ -0,0 +1,23 @@
+# 12 实施计划与里程碑
+
+## 职责
+
+描述实施顺序、任务拆分、依赖、里程碑和验收路径。
+
+## 里程碑
+
+| Milestone | 目标 | 入口条件 | 完成证据 |
+| --- | --- | --- | --- |
+| M1 | TBD | 05/09/13 ready | TBD |
+
+## WBS
+
+| Task ID | 任务 | 关联 REQ | 依赖 | 验证 |
+| --- | --- | --- | --- | --- |
+| TASK-001 | TBD | REQ-001 | none | 13 |
+
+## 任务落盘规则
+
+- 确认后的实现任务进入 `task.json`。
+- P0/P1 `feature_impl` 必须携带架构约束、禁止实现和验证命令。
+- 不在本文新增未经过 03-05 确认的需求。

package/package-source/docs/codex-harness-engineering/templates/spec/13-test-strategy.md

@@ -0,0 +1,26 @@
+# 13 测试策略与质量门禁
+
+## 职责
+
+定义测试分层、测试用例、CI 门禁、证据路径和失败处理。
+
+## 测试分层
+
+| 层级 | 类型 | 覆盖目标 | 命令 |
+| --- | --- | --- | --- |
+| L1 | lint/static | 格式与静态检查 | `git diff --check` |
+| L2 | unit | 纯逻辑 | TBD |
+| L3 | integration | 真实边界 | TBD |
+| L4 | e2e | 用户路径 | TBD |
+
+## 测试用例
+
+| TC ID | 关联 REQ | 断言 | 层级 | 证据 |
+| --- | --- | --- | --- | --- |
+| TC-001 | REQ-001 | TBD | L3 | TBD |
+
+## 门禁
+
+- P0/P1 REQ 必须有 TC 或明确豁免。
+- 完成声明必须包含成功态和失败态证据。
+- 文档改动至少运行 `git diff --check`。

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

@@ -0,0 +1,24 @@
+# 14 需求追踪矩阵 RTM
+
+## 职责
+
+对齐 REQ、规则、API、数据、设计、测试和证据。本文用于发布前对账。
+
+## RTM
+
+| REQ ID | PRD/Rule | FSD | API | Data | Test | Evidence | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | RULE-001 | 06 | API-001 | 10 | TC-001 | TBD | draft |
+
+## 反向检查
+
+| 对象 | Owner | 是否有上游 REQ | 是否有测试 |
+| --- | --- | --- | --- |
+| API-001 | TBD | yes | TBD |
+
+## 发布前检查
+
+- 所有 P0 REQ 有 AC。
+- 所有 P0 REQ 有 TC 或豁免。
+- 所有公开 API 有 REQ owner。
+- 所有完成声明有证据路径。

package/package-source/docs/codex-harness-engineering/templates/spec/spec-manifest.json

@@ -0,0 +1,27 @@
+{
+  "project": "<project-name>",
+  "specVersion": "1.0",
+  "status": "draft",
+  "documents": [
+    { "id": "01", "path": "docs/spec/01-spec-guide-and-index.md", "stage": "Meta", "status": "draft", "owner": "spec-maintainer" },
+    { "id": "02", "path": "docs/spec/02-requirement-sources.md", "stage": "Meta", "status": "draft", "owner": "product" },
+    { "id": "03", "path": "docs/spec/03-proposal-and-scope.md", "stage": "Proposal", "status": "draft", "owner": "product" },
+    { "id": "04", "path": "docs/spec/04-prd.md", "stage": "Proposal", "status": "draft", "owner": "product" },
+    { "id": "05", "path": "docs/spec/05-user-stories-and-acceptance.md", "stage": "Spec", "status": "draft", "owner": "product" },
+    { "id": "06", "path": "docs/spec/06-functional-spec.md", "stage": "Spec", "status": "draft", "owner": "frontend" },
+    { "id": "07", "path": "docs/spec/07-nfr.md", "stage": "Spec", "status": "draft", "owner": "architecture" },
+    { "id": "08", "path": "docs/spec/08-architecture-design.md", "stage": "Design", "status": "draft", "owner": "architecture" },
+    { "id": "09", "path": "docs/spec/09-api-contract.md", "stage": "Design", "status": "draft", "owner": "backend" },
+    { "id": "10", "path": "docs/spec/10-data-model.md", "stage": "Design", "status": "draft", "owner": "backend" },
+    { "id": "11", "path": "docs/spec/11-security-design.md", "stage": "Design", "status": "draft", "owner": "security" },
+    { "id": "12", "path": "docs/spec/12-implementation-plan.md", "stage": "Plan", "status": "draft", "owner": "tech-lead" },
+    { "id": "13", "path": "docs/spec/13-test-strategy.md", "stage": "Test", "status": "draft", "owner": "qa" },
+    { "id": "14", "path": "docs/spec/14-rtm.md", "stage": "Trace", "status": "draft", "owner": "qa" }
+  ],
+  "traceRules": {
+    "requirementPrefix": "REQ-",
+    "acceptancePrefix": "AC-",
+    "testCasePrefix": "TC-",
+    "apiPrefix": "API-"
+  }
+}

package/package-source/docs/codex-harness-engineering/templates/spec/spec-manifest.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://codex-harness.local/schemas/spec-manifest.schema.json",
+  "title": "Codex Harness Spec Manifest",
+  "type": "object",
+  "required": ["project", "specVersion", "status", "documents", "traceRules"],
+  "properties": {
+    "project": { "type": "string", "minLength": 1 },
+    "specVersion": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "enum": ["draft", "review", "approved", "archived"] },
+    "documents": {
+      "type": "array",
+      "minItems": 14,
+      "items": {
+        "type": "object",
+        "required": ["id", "path", "stage", "status", "owner"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^(0[1-9]|1[0-4])$" },
+          "path": { "type": "string", "pattern": "^docs/spec/.+" },
+          "stage": { "type": "string", "enum": ["Meta", "Proposal", "Spec", "Design", "Plan", "Test", "Trace"] },
+          "status": { "type": "string", "enum": ["draft", "review", "approved", "archived"] },
+          "owner": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "traceRules": {
+      "type": "object",
+      "required": ["requirementPrefix", "acceptancePrefix", "testCasePrefix", "apiPrefix"],
+      "properties": {
+        "requirementPrefix": { "type": "string", "minLength": 1 },
+        "acceptancePrefix": { "type": "string", "minLength": 1 },
+        "testCasePrefix": { "type": "string", "minLength": 1 },
+        "apiPrefix": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

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

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

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

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

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

@@ -0,0 +1,48 @@
+# 证据协议
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 必需证据
+
+- 执行过的命令
+- 退出码 / 结论
+- 适用时的截图或日志路径
+- 关联的 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 只应汇总能够回溯到当前任务的证据。