# Trace Format 模板

## 1. 文件命名

```text
traces/<task-id>-<yyyyMMdd-HHmmss>.json
```

当任务真正进入实现 / review 会话并产生日志文件时，相关日志目录应与顶层 trace 使用同一时间戳：

```text
traces/<task-id>-<yyyyMMdd-HHmmss>/
  prompt.txt
  stdout.log
  stderr.log
  final.txt
```

不要再默认使用 `<task-id>-<guid>/` 目录名，也不要在目录内重复拼接 `<task-id>-<timestamp>-<kind>` 文件名。

## 2. 必需字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | 当前任务 id |
| `agent` | string | 执行代理，如 `codex` |
| `started_at` | string | ISO 8601 开始时间 |
| `ended_at` | string | ISO 8601 结束时间 |
| `status` | enum | `passed`、`failed`、`blocked` |
| `commands` | array | 执行命令和退出码 |
| `stage1_review` | object | Stage 1 审查 verdict、退出码和摘要 |
| `stage2_review` | object | Stage 2 审查 verdict、退出码和摘要 |

## 3. 推荐字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_session_id` | string | 当前 task 的 fresh session id |
| `task_kind` | string | 任务类型，例如 `harness`、`smoke`、`feature_impl` |
| `gate_profile` | string | 本任务启用的 gate 强度 |
| `schema_version` | string | trace schema 版本 |
| `session_dir` | string/null | 当前 task session 的持久日志目录；如果任务在 precheck 阶段就被阻断，可为空 |
| `events_file` | string/null | implementation 阶段主 Codex JSONL 事件流文件；review JSONL 如有保留，仍记录在 `log_files` / `logs` |
| `log_files` | array | implementation / review / test output 等日志文件路径；0 字节空日志应在写 trace 前清理 |
| `evidence_files` | array | 与当前任务关联的额外证据附件 |
| `role` | string | 当前 Agent 的角色，例如 `frontend`、`backend`、`reviewer` |
| `model` | string | 实际使用的模型 |
| `reasoning_effort` | enum | 实际使用的思考深度: `none`、`low`、`medium`、`high`、`xhigh` |
| `model_policy` | object | 模型策略来源，例如 policy 文件和 role 覆盖路径 |
| `required_truth_sources` | array | 本任务必须满足的 truth source 类型 |
| `files_changed` | array | Git 检测到的文件 |
| `risk_review_summary` | string/null | 本轮编码执行层风险审查摘要，通常来自最终报告中的风险审查段落 |
| `failure_triage_summary` | string/null | 测试失败时的归因摘要 |
| `failure_triage_report` | string/null | failure triage 结构化报告路径 |
| `evidence_gate_status` | enum/null | `PASS`、`FAIL`、`NOT_RUN`、`UNKNOWN`；用于阻断“测试绿但证据空”的情况 |
| `repair_queue` | array | 当前失败或阻塞留下的修复队列摘要 |
| `public_api_changes` | array | 本轮声明或发现的公共 API / 契约改动项 |
| `sensitive_data_findings` | array | 敏感信息脱敏检查结果或发现项 |
| `error_handling_findings` | array | 异常处理审查结果，尤其是静默吞错、伪成功 fallback 等问题 |
| `blocked_reason` | string/null | 阻塞原因 |
| `final_message` | string | Codex 最终消息摘要 |
| `test_command` | string | 当前任务验证命令 |
| `qa_evidence` | object/null | 测试用例、Oracle、证据文件、副作用断言、假测试检测和失败复现摘要 |
| `implementation_plan_summary` | object/null | 实现前约定的修改文件、改动顺序、文档更新、停止条件、审批与 out-of-scope 摘要 |
| `depth_protocol` | object/null | 输入契约、Recon、影响面、实现计划、测试计划、自检和证据总结等阶段是否被声明为 required，以及是否存在对应摘要 |
| `failed_stage` | string/null | 失败发生在哪个 gate |
| `unexpected_paths` | array | commit path ownership gate 阻断时记录超出 `owned_paths` / runtime allowlist 的路径 |
| `review_context` | object | Stage 1 / Stage 2 对照的真相源文件集合 |
| `truth_source_state` | array | truth source 满足情况、已找到路径和缺失项 |
| `knowledge_references` | array | 当前任务读取并实际使用的知识条目 |
| `knowledge_outputs` | array | 当前任务新增、更新或建议归档的知识条目 |
| `archive_summary` | object/null | 归档阶段对知识引用、知识产出和成熟度变化的摘要 |
| `logs` | object | implementation / stage review / test output 的日志文件路径 |

## 3.1 `qa_evidence` 推荐结构

```json
{
  "case_ids": ["TC-ORDER-CANCEL-007"],
  "requirement_ids": ["REQ-ORDER-003"],
  "oracles": ["response", "database", "event", "audit", "no_side_effect"],
  "evidence_files": ["artifacts/tests/order-cancel-007.json"],
  "side_effect_checks": ["db_snapshot_before_after", "event_not_emitted"],
  "anti_fake_checks": {
    "has_semantic_assertion": true,
    "verifies_side_effect": true,
    "source_bound": true,
    "target_path_proven": true
  },
  "failure_repro": null
}
```

## 3.2 `implementation_plan_summary` 推荐结构

```json
{
  "files_to_modify": [
    {
      "path": "src/orders/cancel-order.ts",
      "reason": "把取消订单规则收敛到领域服务，而不是散落在路由层"
    }
  ],
  "change_order": [
    "先补 RED 测试，再改领域服务，最后更新验收与证据文档"
  ],
  "files_not_to_modify": [
    "src/payments/"
  ],
  "test_first_plan": [
    "先运行订单取消 RED 命令，确认失败原因是目标行为缺失"
  ],
  "documentation_update_plan": [
    "更新 docs/testing/verify-matrix.md 中对应 Requirement ID 的验收链路"
  ],
  "stop_conditions": [
    "如果发现必须修改 payment service 或 lockfile，停止并回到人工确认"
  ],
  "split_recommendation": {
    "needed": false,
    "reason": "当前任务仍可在单个 story 内闭环",
    "suggested_splits": []
  },
  "human_approval_requirement": {
    "required": true,
    "approval_source": "CHG-2026-0512",
    "unblock_condition": "变更单批准后才能改 release 配置"
  },
  "out_of_scope_items": [
    "退款链路",
    "库存回补重构"
  ]
}
```

## 4. 校验

使用 `docs/harness/trace.schema.json` 校验 trace。CI 中可以用任意 JSON Schema validator 执行。

## 5. 可观测性最低要求

如果任务涉及 API、异步链路、外部系统、权限、支付、删除、上传或关键业务闭环，相关证据中至少应能回答：

- 请求 ID 是什么
- 用户 ID / actor 是什么
- 接口路径或业务入口是什么
- 失败原因是什么
- 耗时是多少
- 是否存在审计记录
- 是否有对应告警或失败通知
