@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/docs/team-knowledge-sync.md

@@ -1,187 +1,187 @@
-# Team Knowledge Sync
-
-本文定义项目级 `docs/knowledge/` 与可选团队知识库之间的同步协议。团队知识库是知识复利层，不是 driver 的运行依赖；没有外部知识库时，本地任务仍必须可以完成、验证和提交。
-
-## 目标
-
-- 把项目中已经验证的通用经验提升为团队资产。
-- 让多个项目共享同一套技术知识、业务知识和团队约定。
-- 用 Git、Markdown 和追加日志保留知识来源、贡献者、验证证据和冲突处理记录。
-- 避免把未验证的单次经验直接升级为全局规则或团队规范。
-
-## 推荐仓库结构
-
-团队知识库建议独立成 Git 仓库，不寄生在任何业务项目中：
-
-```text
-team-knowledge/
-  knowledge-catalog.md        # 团队级全景入口
-  .knowledge-config.yaml      # 成员、角色、同步和冲突策略
-  log.md                      # 只追加的知识变更日志
-  team-conventions/           # Layer 0-T: 团队约定
-  tech-wiki/                  # Layer 1: 跨项目技术知识
-    catalog.md
-  biz-wiki/<domain>/          # Layer 2: 领域业务知识
-    catalog.md
-  project-profiles/           # 项目画像和知识源映射
-  contributions/
-    pending/                  # 待合并贡献
-    conflicts/                # 内容矛盾和人工裁决项
-```
-
-项目仓库只保存 Layer 3 项目知识：
-
-```text
-docs/knowledge/
-  knowledge-catalog.md
-  catalog.md
-  models/
-  decisions/
-  guidelines/
-  pitfalls/
-  processes/
-  archive/
-```
-
-## 角色
-
-| 角色 | 权限 | 典型职责 |
-| --- | --- | --- |
-| `maintainer` | 审批 proven、裁决冲突、维护目录和成员 | 决定团队知识是否升级为约定、规则或模板 |
-| `contributor` | 提交新条目、追加 evidence、标记冲突 | 从项目归档中输出 `contributions/pending/` |
-| `reader` | 读取知识，不写入团队仓库 | 新成员、外部协作方、只读自动化 |
-
-角色只影响团队知识库写入权限，不影响项目本地 `docs/knowledge/` 的归档任务。
-
-## 配置建议
-
-`.knowledge-config.yaml` 可使用以下最小形状：
-
-```yaml
-team:
-  name: example-team
-  default_role: reader
-roles:
-  maintainers: []
-  contributors: []
-sync:
-  accept_layers: [tech-wiki, biz-wiki]
-  default_domain:
-  require_maintainer_for_proven: true
-conflicts:
-  on_content_conflict: stage_to_conflicts
-  on_maturity_conflict: keep_lower_and_mark_contradiction
-```
-
-项目 driver 不应依赖该配置存在。缺少配置时，只输出候选报告，不直接写外部仓库。
-
-## 贡献流程
-
-1. `ARCHIVE-*` 从本轮 trace、review、failure triage 和 `progress.txt` 中提取项目知识。
-2. 条目先进入项目 `docs/knowledge/`，新增条目默认 `maturity: draft`。
-3. `KNOWLEDGE-TEAM-SYNC-*` 只挑选具备跨项目价值的 `verified` 或 `proven` 候选。
-4. 候选写入团队仓库 `contributions/pending/`，保留项目来源、贡献者、验证证据和建议目标层。
-5. maintainer 审核后合入 `tech-wiki/`、`biz-wiki/<domain>/` 或 `team-conventions/`。
-6. 合入时追加 `log.md`，记录日期、动作、贡献者、来源项目、条目 ID 和 evidence。
-
-## 自动合并与冲突策略
-
-| 情况 | 默认处理 |
-| --- | --- |
-| 不同 ID 的纯新增条目 | 可自动进入 `contributions/pending/` |
-| 同一条目追加 `evidence`、`last_referenced` 或 `contributors` | 可自动合并并去重 |
-| `draft -> verified` | 需要至少一个真实任务引用并有验证证据 |
-| `verified -> proven` | 需要两个不同任务或项目的证据，或 maintainer 明确审批 |
-| 内容结论相反 | 写入 `contributions/conflicts/`，等待 maintainer 裁决 |
-| 一方提升成熟度、一方降级成熟度 | 保留较低成熟度并标记 `contradiction` |
-| 删除或归档团队知识 | 必须有人类审批和 `log.md` 记录 |
-
-自动化只能生成候选、追加 evidence、修复索引；不得静默删除团队知识或把单次经验提升为 `proven`。
-
-## 追加日志
-
-`log.md` 只追加，不重写历史。推荐格式：
-
-```markdown
-## [2026-05-12] promote | <contributor> | <source-project> | +1 guideline | #<trace-or-commit>
-- GUIDELINE-API-001: 分页接口必须声明稳定排序字段 (verified -> proven)
-```
-
-每次团队知识变更至少记录：
-
-- action: `ingest`、`verify`、`promote`、`decay`、`conflict`、`archive`
-- contributor
-- source project
-- source trace、commit、review finding 或文档路径
-- affected knowledge IDs
-
-## 条目元数据补充
-
-团队知识条目除项目知识的基本 frontmatter 外，建议补充：
-
-```yaml
-evidence:
-  contributors:
-    - name: codex
-      source_project: example-project
-      source_ref: traces/TASK-001-20260512.json
-  last_referenced:
-  validated_projects: []
-  contradictions: []
-```
-
-如果项目知识仍使用简化 frontmatter，也应在同步候选里补齐 evidence，而不是丢失来源。
-
-## 降级与失败处理
-
-- 团队知识仓库不可用时，任务只能记录 `blocked_external_knowledge_sync` 或输出候选报告，不应阻塞本地实现验证。
-- 外部仓库 push 失败时，不要伪造已同步状态；把候选保留在项目报告或本地 pending 文件里。
-- 外部知识和项目事实冲突时，以当前项目可验证事实为准，并输出 conflict candidate。
-- 衰减和归档必须先形成候选，再由 maintainer 或独立任务确认。
-
-## 任务模板片段
-
-需要把团队知识同步加入 `task.json` 时，可按项目裁剪以下任务。该任务是可选上层能力，不应成为所有项目的默认阻塞任务。
-
-```json
-{
-  "id": "KNOWLEDGE-TEAM-SYNC-001",
-  "description": "把项目知识中的跨项目候选输出到团队知识库贡献暂存区",
-  "task_kind": "archive",
-  "phase": "archive",
-  "gate_profile": "lightweight",
-  "required_truth_sources": ["knowledge"],
-  "priority": 95,
-  "dependencies": ["ARCHIVE-001"],
-  "passes": false,
-  "context_files": [
-    "docs/harness/knowledge-architecture.md",
-    "docs/harness/team-knowledge-sync.md",
-    "docs/knowledge/knowledge-catalog.md",
-    "docs/knowledge/catalog.md"
-  ],
-  "owned_paths": [
-    "docs/knowledge/"
-  ],
-  "execution": { "mode": "single" },
-  "steps": [
-    "读取 promotion candidates，筛选具备跨项目价值的 verified/proven 条目",
-    "如果团队知识库可用，输出 contributions/pending 候选并追加同步报告",
-    "如果团队知识库不可用，仅在项目内记录候选、缺失配置和后续人工步骤",
-    "内容冲突写入 conflict candidate，不直接覆盖团队知识"
-  ],
-  "test_command": "git diff --check",
-  "acceptance": [
-    "同步结果或候选报告可追溯到项目知识条目和 evidence",
-    "没有把 draft 或单次经验直接升级为团队 proven 知识",
-    "外部团队知识库不可用时没有阻塞本地 driver 验证"
-  ]
-}
-```
-
-## 相关文档
-
-- 项目知识架构：`docs/harness/knowledge-architecture.md`
-- 冷启动导入：`docs/harness/knowledge-import.md`
-- 知识健康检查：`docs/harness/knowledge-lint.md`
-- Prompt 知识集成：`docs/harness/prompt-knowledge-integration.md`
+# Team Knowledge Sync
+
+本文定义项目级 `docs/knowledge/` 与可选团队知识库之间的同步协议。团队知识库是知识复利层，不是 driver 的运行依赖；没有外部知识库时，本地任务仍必须可以完成、验证和提交。
+
+## 目标
+
+- 把项目中已经验证的通用经验提升为团队资产。
+- 让多个项目共享同一套技术知识、业务知识和团队约定。
+- 用 Git、Markdown 和追加日志保留知识来源、贡献者、验证证据和冲突处理记录。
+- 避免把未验证的单次经验直接升级为全局规则或团队规范。
+
+## 推荐仓库结构
+
+团队知识库建议独立成 Git 仓库，不寄生在任何业务项目中：
+
+```text
+team-knowledge/
+  knowledge-catalog.md        # 团队级全景入口
+  .knowledge-config.yaml      # 成员、角色、同步和冲突策略
+  log.md                      # 只追加的知识变更日志
+  team-conventions/           # Layer 0-T: 团队约定
+  tech-wiki/                  # Layer 1: 跨项目技术知识
+    catalog.md
+  biz-wiki/<domain>/          # Layer 2: 领域业务知识
+    catalog.md
+  project-profiles/           # 项目画像和知识源映射
+  contributions/
+    pending/                  # 待合并贡献
+    conflicts/                # 内容矛盾和人工裁决项
+```
+
+项目仓库只保存 Layer 3 项目知识：
+
+```text
+docs/knowledge/
+  knowledge-catalog.md
+  catalog.md
+  models/
+  decisions/
+  guidelines/
+  pitfalls/
+  processes/
+  archive/
+```
+
+## 角色
+
+| 角色 | 权限 | 典型职责 |
+| --- | --- | --- |
+| `maintainer` | 审批 proven、裁决冲突、维护目录和成员 | 决定团队知识是否升级为约定、规则或模板 |
+| `contributor` | 提交新条目、追加 evidence、标记冲突 | 从项目归档中输出 `contributions/pending/` |
+| `reader` | 读取知识，不写入团队仓库 | 新成员、外部协作方、只读自动化 |
+
+角色只影响团队知识库写入权限，不影响项目本地 `docs/knowledge/` 的归档任务。
+
+## 配置建议
+
+`.knowledge-config.yaml` 可使用以下最小形状：
+
+```yaml
+team:
+  name: example-team
+  default_role: reader
+roles:
+  maintainers: []
+  contributors: []
+sync:
+  accept_layers: [tech-wiki, biz-wiki]
+  default_domain:
+  require_maintainer_for_proven: true
+conflicts:
+  on_content_conflict: stage_to_conflicts
+  on_maturity_conflict: keep_lower_and_mark_contradiction
+```
+
+项目 driver 不应依赖该配置存在。缺少配置时，只输出候选报告，不直接写外部仓库。
+
+## 贡献流程
+
+1. `ARCHIVE-*` 从本轮 trace、review、failure triage 和 `progress.txt` 中提取项目知识。
+2. 条目先进入项目 `docs/knowledge/`，新增条目默认 `maturity: draft`。
+3. `KNOWLEDGE-TEAM-SYNC-*` 只挑选具备跨项目价值的 `verified` 或 `proven` 候选。
+4. 候选写入团队仓库 `contributions/pending/`，保留项目来源、贡献者、验证证据和建议目标层。
+5. maintainer 审核后合入 `tech-wiki/`、`biz-wiki/<domain>/` 或 `team-conventions/`。
+6. 合入时追加 `log.md`，记录日期、动作、贡献者、来源项目、条目 ID 和 evidence。
+
+## 自动合并与冲突策略
+
+| 情况 | 默认处理 |
+| --- | --- |
+| 不同 ID 的纯新增条目 | 可自动进入 `contributions/pending/` |
+| 同一条目追加 `evidence`、`last_referenced` 或 `contributors` | 可自动合并并去重 |
+| `draft -> verified` | 需要至少一个真实任务引用并有验证证据 |
+| `verified -> proven` | 需要两个不同任务或项目的证据，或 maintainer 明确审批 |
+| 内容结论相反 | 写入 `contributions/conflicts/`，等待 maintainer 裁决 |
+| 一方提升成熟度、一方降级成熟度 | 保留较低成熟度并标记 `contradiction` |
+| 删除或归档团队知识 | 必须有人类审批和 `log.md` 记录 |
+
+自动化只能生成候选、追加 evidence、修复索引；不得静默删除团队知识或把单次经验提升为 `proven`。
+
+## 追加日志
+
+`log.md` 只追加，不重写历史。推荐格式：
+
+```markdown
+## [2026-05-12] promote | <contributor> | <source-project> | +1 guideline | #<trace-or-commit>
+- GUIDELINE-API-001: 分页接口必须声明稳定排序字段 (verified -> proven)
+```
+
+每次团队知识变更至少记录：
+
+- action: `ingest`、`verify`、`promote`、`decay`、`conflict`、`archive`
+- contributor
+- source project
+- source trace、commit、review finding 或文档路径
+- affected knowledge IDs
+
+## 条目元数据补充
+
+团队知识条目除项目知识的基本 frontmatter 外，建议补充：
+
+```yaml
+evidence:
+  contributors:
+    - name: codex
+      source_project: example-project
+      source_ref: traces/TASK-001-20260512.json
+  last_referenced:
+  validated_projects: []
+  contradictions: []
+```
+
+如果项目知识仍使用简化 frontmatter，也应在同步候选里补齐 evidence，而不是丢失来源。
+
+## 降级与失败处理
+
+- 团队知识仓库不可用时，任务只能记录 `blocked_external_knowledge_sync` 或输出候选报告，不应阻塞本地实现验证。
+- 外部仓库 push 失败时，不要伪造已同步状态；把候选保留在项目报告或本地 pending 文件里。
+- 外部知识和项目事实冲突时，以当前项目可验证事实为准，并输出 conflict candidate。
+- 衰减和归档必须先形成候选，再由 maintainer 或独立任务确认。
+
+## 任务模板片段
+
+需要把团队知识同步加入 `task.json` 时，可按项目裁剪以下任务。该任务是可选上层能力，不应成为所有项目的默认阻塞任务。
+
+```json
+{
+  "id": "KNOWLEDGE-TEAM-SYNC-001",
+  "description": "把项目知识中的跨项目候选输出到团队知识库贡献暂存区",
+  "task_kind": "archive",
+  "phase": "archive",
+  "gate_profile": "lightweight",
+  "required_truth_sources": ["knowledge"],
+  "priority": 95,
+  "dependencies": ["ARCHIVE-001"],
+  "passes": false,
+  "context_files": [
+    "docs/harness/knowledge-architecture.md",
+    "docs/harness/team-knowledge-sync.md",
+    "docs/knowledge/knowledge-catalog.md",
+    "docs/knowledge/catalog.md"
+  ],
+  "owned_paths": [
+    "docs/knowledge/"
+  ],
+  "execution": { "mode": "single" },
+  "steps": [
+    "读取 promotion candidates，筛选具备跨项目价值的 verified/proven 条目",
+    "如果团队知识库可用，输出 contributions/pending 候选并追加同步报告",
+    "如果团队知识库不可用，仅在项目内记录候选、缺失配置和后续人工步骤",
+    "内容冲突写入 conflict candidate，不直接覆盖团队知识"
+  ],
+  "test_command": "git diff --check",
+  "acceptance": [
+    "同步结果或候选报告可追溯到项目知识条目和 evidence",
+    "没有把 draft 或单次经验直接升级为团队 proven 知识",
+    "外部团队知识库不可用时没有阻塞本地 driver 验证"
+  ]
+}
+```
+
+## 相关文档
+
+- 项目知识架构：`docs/harness/knowledge-architecture.md`
+- 冷启动导入：`docs/harness/knowledge-import.md`
+- 知识健康检查：`docs/harness/knowledge-lint.md`
+- Prompt 知识集成：`docs/harness/prompt-knowledge-integration.md`

package/package-source/docs/codex-harness-engineering/templates/docs/trace-format.md

@@ -39,36 +39,48 @@ traces/<task-id>-<yyyyMMdd-HHmmss>.json
 | `files_changed` | array | Git 检测到的文件 |
 | `blocked_reason` | string/null | 阻塞原因 |
 | `final_message` | string | Codex 最终消息摘要 |
-| `test_command` | string | 当前任务验证命令 |
-| `qa_evidence` | object/null | 测试用例、Oracle、证据文件、副作用断言、假测试检测和失败复现摘要 |
-| `failed_stage` | string/null | 失败发生在哪个 gate |
+| `test_command` | string | 当前任务验证命令 |
+| `qa_evidence` | object/null | 测试用例、Oracle、证据文件、副作用断言、假测试检测和失败复现摘要 |
+| `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
-}
-```
-
-## 4. 校验
-
-使用 `docs/harness/trace.schema.json` 校验 trace。CI 中可以用任意 JSON Schema validator 执行。
+| `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
+}
+```
+
+## 4. 校验
+
+使用 `docs/harness/trace.schema.json` 校验 trace。CI 中可以用任意 JSON Schema validator 执行。
+
+## 5. 可观测性最低要求
+
+如果任务涉及 API、异步链路、外部系统、权限、支付、删除、上传或关键业务闭环，相关证据中至少应能回答：
+
+- 请求 ID 是什么
+- 用户 ID / actor 是什么
+- 接口路径或业务入口是什么
+- 失败原因是什么
+- 耗时是多少
+- 是否存在审计记录
+- 是否有对应告警或失败通知

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

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放治理侧的策略、风险分级、保护清单和反馈回路模板。
+
+## 结构索引
+
+- `sandbox-policy.md`：权限和沙箱策略。
+- `risk-levels.yaml`：风险分级。
+- `retry-budget.yaml`：重试预算。
+- `branch-protection-checklist.md`：分支保护清单。
+- `feedback-evolution-loop.md`：经验回流机制。
+
+## 修改规则
+
+- 这里定义的是“治理口径”，不是具体 task 细节。
+- 修改风险分级或策略时，要检查 driver、review 和 docs 是否需要同步解释。

package/package-source/docs/codex-harness-engineering/templates/governance/branch-protection-checklist.md

@@ -1,50 +1,50 @@
-# Branch Protection Checklist 模板
-
-## 1. 受保护分支
-
-- [ ] `main`
-- [ ] `release/*`
-- [ ] `hotfix/*`
-
-## 2. Required Status Checks
-
-- [ ] `lint`
-- [ ] `typecheck`
-- [ ] `unit-test`
-- [ ] `build`
-- [ ] `contract-validate`
-- [ ] `e2e`
-- [ ] `visual-regression`
-- [ ] `codex-stage1-review`
-- [ ] `codex-stage2-review`
-
-说明:
-
-- GitHub required checks 对 GitHub Actions 使用的是 **job name**，不是 step 名。
-- required checks 使用的 job 名必须在所有 workflow 中唯一，避免出现歧义。
-- 如果某个 required check job 依赖其他 job，建议配合 `needs` + `always()`，确保检查名始终实际出现。
-
-## 3. 合并策略
-
-- [ ] 禁止绕过 required status checks
-- [ ] 禁止在 checks 缺失时自动合并
-- [ ] 仅允许 squash / merge / rebase 中的指定策略
-- [ ] L2/L3 风险变更必须人工审批
-
-## 4. Review 策略
-
-- [ ] 至少 1 位 reviewer
-- [ ] 高风险目录要求指定 owner 审核
-- [ ] AI 自动 PR 不得自审自合
-
-## 5. 特权与例外
-
-- 可 bypass 的角色:
-- 可 bypass 的场景:
-- 需要补追溯记录的场景:
-
-## 6. 上线前检查
-
-- [ ] 回滚方案可用
-- [ ] smoke test 已运行
-- [ ] 关键监控已开启
+# Branch Protection Checklist 模板
+
+## 1. 受保护分支
+
+- [ ] `main`
+- [ ] `release/*`
+- [ ] `hotfix/*`
+
+## 2. Required Status Checks
+
+- [ ] `lint`
+- [ ] `typecheck`
+- [ ] `unit-test`
+- [ ] `build`
+- [ ] `contract-validate`
+- [ ] `e2e`
+- [ ] `visual-regression`
+- [ ] `codex-stage1-review`
+- [ ] `codex-stage2-review`
+
+说明:
+
+- GitHub required checks 对 GitHub Actions 使用的是 **job name**，不是 step 名。
+- required checks 使用的 job 名必须在所有 workflow 中唯一，避免出现歧义。
+- 如果某个 required check job 依赖其他 job，建议配合 `needs` + `always()`，确保检查名始终实际出现。
+
+## 3. 合并策略
+
+- [ ] 禁止绕过 required status checks
+- [ ] 禁止在 checks 缺失时自动合并
+- [ ] 仅允许 squash / merge / rebase 中的指定策略
+- [ ] L2/L3 风险变更必须人工审批
+
+## 4. Review 策略
+
+- [ ] 至少 1 位 reviewer
+- [ ] 高风险目录要求指定 owner 审核
+- [ ] AI 自动 PR 不得自审自合
+
+## 5. 特权与例外
+
+- 可 bypass 的角色:
+- 可 bypass 的场景:
+- 需要补追溯记录的场景:
+
+## 6. 上线前检查
+
+- [ ] 回滚方案可用
+- [ ] smoke test 已运行
+- [ ] 关键监控已开启