@pzy560117/codex-harness 0.1.4 → 0.1.6

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

@@ -0,0 +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`

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

@@ -0,0 +1,86 @@
+# Trace Format 模板
+
+## 1. 文件命名
+
+```text
+traces/<task-id>-<yyyyMMdd-HHmmss>.json
+```
+
+## 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 | 当前 task session 的持久日志目录 |
+| `events_file` | string/null | implementation 阶段主 Codex JSONL 事件流文件；review JSONL 如有保留，仍记录在 `log_files` / `logs` |
+| `log_files` | array | implementation / review / test output 等日志文件路径 |
+| `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 检测到的文件 |
+| `blocked_reason` | string/null | 阻塞原因 |
+| `final_message` | string | Codex 最终消息摘要 |
+| `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 执行。
+
+## 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

@@ -0,0 +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 已运行
+- [ ] 关键监控已开启

package/package-source/docs/codex-harness-engineering/templates/governance/feedback-evolution-loop.md

@@ -0,0 +1,55 @@
+# Feedback / Evolution Loop 模板
+
+## 1. 目标
+
+把重复出现的用户修正、审查失败和回归问题，从“聊天提醒”升级成“仓库规则”。
+
+## 2. 反馈来源
+
+- 用户直接纠正
+- Stage 1 review 失败
+- Stage 2 review 失败
+- verify 失败
+- E2E / visual regression 失败
+- 发布后回滚或线上事故
+
+## 3. 反馈记录格式
+
+| 日期 | 来源 | 触发信号 | 具体问题 | 临时修复 | 可沉淀规则 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 2026-04-22 | review | Stage 1 FAIL | 设计稿未同步更新 | 补设计稿 | UI 变更前必须更新设计稿 | open |
+
+## 4. 升级规则
+
+- 同类反馈出现 1 次: 记录到反馈表。
+- 同类反馈出现 2 次: 加入检查清单或 review 必查项。
+- 同类反馈出现 3 次及以上: 升级为模板、driver、Skill 或治理规则。
+
+## 5. 处理优先级
+
+1. 能被确定性脚本拦截的，优先脚本化。
+2. 能被 review 清单拦截的，加入 Stage 1 / Stage 2 模板。
+3. 能被真相源文档避免的，补 Product / Design / DEV-PLAN 模板。
+4. 最后才是单纯写经验说明。
+
+## 6. 常见升级方向
+
+- 需求误解 -> 更新 `prd-lite.md` / `acceptance-criteria.md`
+- 设计缺口 -> 更新 `design-brief.md` / `screen-states.md`
+- 任务切分过粗 -> 更新 `dev-plan.md`
+- 审查漏项 -> 更新 Stage 1 / Stage 2 review 模板
+- 验证不足 -> 更新 `tools/harness/verify.ps1`、`test_command`、CI
+
+## 7. Session 启动检查
+
+新 session 开始前，至少确认：
+
+- 有没有未处理的高频反馈
+- 有没有需要毕业为正式规则的事项
+- 当前模板是否已经同步这些规则
+
+## 8. 完成标准
+
+- 反馈不只被记录，而且被归类。
+- 高频问题已经迁移到模板、脚本或检查清单。
+- 同一类错误不会反复依赖人工口头提醒。

package/package-source/docs/codex-harness-engineering/templates/governance/retry-budget.yaml

@@ -0,0 +1,30 @@
+retry_policy:
+  max_attempts_per_task: 3
+  max_attempts_per_pr: 2
+  max_runtime_minutes_per_attempt: 30
+  max_changed_files_per_attempt: 20
+  cooldown_minutes_between_attempts: 10
+
+escalation_conditions:
+  - "同一验证命令连续失败 2 次"
+  - "修改文件数超过预算"
+  - "出现权限、密钥、生产环境依赖"
+  - "任务描述互相矛盾"
+  - "工作区不干净且无法归因"
+
+stop_conditions:
+  - "任务进入 BLOCKED"
+  - "风险等级升到 L3"
+  - "需要人工产品决策"
+  - "required status checks 缺失"
+
+allowed_retry_reasons:
+  - "lint/typecheck/build 失败"
+  - "测试用例缺失"
+  - "文档与代码不一致"
+
+disallowed_retry_reasons:
+  - "未知生产事故"
+  - "凭证缺失"
+  - "权限不足"
+  - "需要人工确认的数据修复"

package/package-source/docs/codex-harness-engineering/templates/governance/risk-levels.yaml

@@ -0,0 +1,53 @@
+levels:
+  L0:
+    description: "低风险文档或局部非运行时代码修改"
+    allowed_actions:
+      - "auto-fix"
+      - "auto-pr"
+      - "auto-merge"
+    required_checks:
+      - "git diff --check"
+    requires_human_approval: false
+    auto_merge_allowed: true
+
+  L1:
+    description: "常规功能改动，影响范围清晰，可由测试充分覆盖"
+    allowed_actions:
+      - "auto-fix"
+      - "auto-pr"
+    required_checks:
+      - "lint"
+      - "typecheck"
+      - "unit-test"
+      - "build"
+    requires_human_approval: false
+    auto_merge_allowed: false
+
+  L2:
+    description: "跨模块改动、接口变更、关键页面交互变更"
+    allowed_actions:
+      - "auto-pr"
+    required_checks:
+      - "lint"
+      - "typecheck"
+      - "unit-test"
+      - "integration-test"
+      - "contract-validate"
+      - "e2e"
+    requires_human_approval: true
+    auto_merge_allowed: false
+
+  L3:
+    description: "高风险改动，涉及权限、支付、迁移、删除、生产安全"
+    allowed_actions:
+      - "draft-pr-only"
+    required_checks:
+      - "lint"
+      - "typecheck"
+      - "unit-test"
+      - "integration-test"
+      - "security-scan"
+      - "manual-review"
+      - "rollback-check"
+    requires_human_approval: true
+    auto_merge_allowed: false

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

@@ -0,0 +1,13 @@
+# 权限策略
+
+## 基本原则
+
+- driver 负责统一执行、记录和提交。
+- 人工会话可以分析和改文档，但不要伪造 driver 结果。
+- 禁止在脏工作区中自动提交。
+- 禁止未经确认回滚、覆盖或删除用户改动。
+
+## 文件边界
+
+- 只修改当前任务要求的文件。
+- 对运行产物的忽略必须通过 `non_blocking_dirty_paths` 显式声明。

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

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放 hook 配置模板和 stop hook 脚本模板。
+
+## 结构索引
+
+- `hooks.json`：hook 配置。
+- `hook-stop-verify.ps1`：stop 时的校验脚本。
+
+## 修改规则
+
+- 这里的脚本影响会话生命周期和自动继续逻辑，改动前要确认不会破坏 driver 正常收口。
+- 不要把项目业务逻辑塞进通用 hook。