coding-agent-harness 1.0.0

package/templates-zh-CN/planning/review.md

@@ -0,0 +1,69 @@
+# [任务名称] - 审查
+
+## 审查者身份（Reviewer Identity）
+
+| Reviewer | Type | Scope |
+| --- | --- | --- |
+| [name] | self / subagent / external / human | [审查范围] |
+
+## 审查范围
+
+- 审查类型：adversarial / security / regression / architecture / release / other
+- 范围内：[文件、模块、行为、运行目标]
+- 范围外：[明确不审查的内容；如无写“无”]
+- 来源材料：[task plan、diff、commit、PR、测试输出、运行证据]
+
+## 信心挑战（Confidence Challenge）
+
+直接回答：你是否对当前计划、实现和策略有 100% 信心？
+
+- Verdict：yes / no
+- 如果不是 100%，剩余漏洞或证据缺口：
+  - [风险 / 漏洞 / 未验证假设；如无写“无”]
+- Fix loop count：[已经执行几轮 review -> fix -> evidence -> review]
+- 当前结论：[为什么现在可以继续、暂停或收口]
+
+## 重要发现（Material Findings，表头供 checker 解析）
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+不要保留示例 finding。若没有重要发现，只保留表头，并补全下面的无重要发现声明。
+
+允许的 `Severity`：`P0`, `P1`, `P2`, `P3`。
+允许的 `Open`：`yes`, `no`。
+允许的 `Disposition`：`open`, `mitigated`, `closed`, `deferred`, `accepted-risk`, `not-reproducible`, `out-of-scope`。
+允许的 `Blocks Release`：`yes`, `no`。
+
+## 非阻塞备注（Non-Material Notes）
+
+- [不阻塞本轮目标但值得记录的问题；如无写“无”]
+
+## 已检查证据（Evidence Checked）
+
+| Evidence ID | Type | Path | Summary |
+| --- | --- | --- | --- |
+| E-001 | command / diff / fixture / screenshot / review / report | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [检查了什么，结论是什么] |
+
+## 无重要发现声明
+
+[如果没有重要发现，明确写：本轮已检查上述证据，未发现阻塞目标的重要发现。]
+
+## 残余风险
+
+| Risk | Owner | Accepted? | Follow-up |
+| --- | --- | --- | --- |
+| [风险] | [负责人] | yes / no | [后续路径或“无”] |
+
+## 后续路由（Follow-Up Routing）
+
+- 任务计划：[是否需要更新，路径或“无”]
+- Progress：[对应 `progress.md` 条目]
+- 发现记录：[是否需要写入 `findings.md`]
+- Regression SSoT：[新增 / 调整 / 无]
+- Lessons SSoT：[checked-created: L-YYYY-MM-DD-NNN / checked-none: 一句话原因]
+- 收口记录：[收口时引用路径]
+
+## 最终信心依据（Final Confidence Basis）
+
+[说明最终信心来自哪些证据、审查层级和已关闭发现。发布前最终审查不能只依赖 self-only。]

package/templates-zh-CN/planning/task_plan.md

@@ -0,0 +1,116 @@
+# [任务名称]
+
+## 目标
+
+[用一句话说明本任务完成后应达到的状态。]
+
+## 范围
+
+- 做什么：[本轮允许修改或交付的内容]
+- 不做什么：[明确排除的内容，避免执行中扩大范围]
+- 主要风险：[当前已知的技术、产品、协作或验证风险]
+
+## 任务信息架构预算
+
+| 预算 | 适用场景 | 必需结构 |
+| --- | --- | --- |
+| simple | 单 owner、无 subagent、证据深度为 L0/L1 | 使用标准任务文件即可 |
+| complex | 需要 L2/L3 证据、subagent/reviewer、外部参考、生成产物，或超过 5 个切片 | 只启用实际需要的可选索引 |
+
+可选子目录按触发条件创建，不作为默认脚手架：
+
+- `references/INDEX.md`：任务本地资料、外部链接、reviewer 输入包、跨仓上下文。
+- `artifacts/INDEX.md`：命令输出、截图、fixture、生成报告、审查记录等证据。
+- `slices/<slice-id>/`：多切片任务。每个切片使用 `brief.md`、`evidence.md`、`review.md`。
+
+没有真实触发条件时，不创建可选目录；已创建则必须有 index 和明确用途。
+
+## 上下文包（Context Packet）
+
+| ID | 类型 | 路径 | 为什么需要 | 使用者 |
+| --- | --- | --- | --- | --- |
+| C-001 | public-doc / private-plan / external / code | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [说明这份上下文如何影响任务] | coordinator / reviewer / worker |
+
+路径前缀约定：
+
+- `PUBLIC:`：公开源仓库中的文件。
+- `PRIVATE:`：私有 harness 仓库中的文件。
+- `TARGET:`：已安装目标项目中的文件。
+- `EXTERNAL:` 或 `URL:`：外部资料。
+
+## 执行与可视化文件
+
+`execution_strategy.md` 和 `visual_roadmap.md` 是本任务的同级合同文件，不嵌入 `task_plan.md`。这样 dashboard 和 checker 可以稳定读取。
+
+| 合同文件 | 是否必需 | 用途 |
+| --- | --- | --- |
+| `execution_strategy.md` | yes | 执行模式、subagent 使用、冲突控制、证据深度、交接规则 |
+| `visual_roadmap.md` | yes | Mermaid 路线图、阶段表、完成度、证据状态、阻塞风险 |
+| `review.md` | 按需 | 对抗性审查、release review、外部 reviewer 结论 |
+
+旧任务可以保留历史嵌入式段落作为 fallback；新任务必须使用独立文件。
+
+## 产物索引（Artifact Index）
+
+简单任务可在这里登记关键证据。产物较多时，创建 `artifacts/INDEX.md` 并在此引用 ID。
+
+| Artifact ID | 类型 | 路径 | 摘要 |
+| --- | --- | --- | --- |
+| A-001 | command / diff / fixture / screenshot / review / report | PUBLIC:path 或 PRIVATE:path 或 TARGET:path 或 EXTERNAL:path 或 URL:https://example.com | [这份证据证明了什么] |
+
+## 步骤
+
+1. [步骤 1]
+2. [步骤 2]
+3. [步骤 3]
+
+## 验收标准
+
+- [ ] [标准 1]
+- [ ] [标准 2]
+- [ ] [标准 3]
+
+## 工作树（Worktree）
+
+- 路径：[worktree 路径，例如 `.worktrees/feat/xxx`]
+- 分支：[分支名]
+- Worker owner：[coordinator / subagent id / 不适用]
+- Worker handoff commit required：[yes / no / 不适用]
+- Coordinator integration branch：[分支名 / 不适用]
+- 未使用 worktree 的原因：[说明]
+
+## 长程任务判定
+
+- 是否属于长程任务：[是 / 否]
+- 若是，合同文件：`long-running-task-contract.md`
+- 连续执行权限：[已授权 / 未授权 / 不适用]
+- Stop Condition 摘要：[一句话说明什么时候必须停]
+
+## 审查判定
+
+- 是否需要对抗性审查：[是 / 否]
+- 若是，报告文件：`review.md`
+- Reviewer：[self / subagent / external / human / 不适用]
+- No-finding 要求：[例如 reviewer 无重要发现 / 不适用]
+
+## 关联
+
+- 功能 SSoT 条目：[引用]
+- 相关 Regression Gate：[引用]
+- 审查报告：[路径 / 不适用]
+- Harness Ledger 条目：[完成时填写 / HL-...]
+- 前置任务：[引用；如无写“无”]
+
+## 模块关联（启用模块并行时填写）
+
+- Module：[module key，例如 reader / graph / 不适用]
+- Step：[step ID，例如 RDR-02 / 不适用]
+- Module Plan：[link to module_plan.md / 不适用]
+
+## 协调者交接（Coordinator，启用模块并行时填写）
+
+- Global sync owner：coordinator / 不适用
+- Global sync status：pending-coordinator-pass / synced / n/a
+- Registry update needed：[module key, step, status, branch, updated / 不适用]
+- Harness Ledger update needed：[task plan path, review path, closeout status / 不适用]
+- Closeout / Regression update needed：[路径或 n/a]

package/templates-zh-CN/planning/visual_roadmap.md

@@ -0,0 +1,24 @@
+# 可视化路线图
+
+本文件供 HTML dashboard 和人工审查同时使用。Mermaid 图展示阶段关系；阶段表提供可解析的状态、完成度和证据状态。
+
+## 阶段关系图（Phase Graph）
+
+```mermaid
+flowchart LR
+  PH01["PH-01 计划确认"] --> PH02["PH-02 实现"]
+  PH02 --> PH03["PH-03 验证"]
+  PH03 --> PH04["PH-04 审查与收口"]
+```
+
+## 阶段表（Phase Table，表头供 checker 解析）
+
+| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
+| --- | --- | --- | ---: | --- | --- | --- | --- | --- |
+| PH-01 | none | planned | 0 | [计划输出] | [必需证据] | missing | none | coordinator |
+
+允许的 `State`：`planned`, `in_progress`, `review`, `blocked`, `done`, `skipped`。
+
+允许的 `Evidence Status`：`missing`, `partial`, `present`, `waived`。
+
+`Completion` 使用 `0..100` 的整数；`done` 应为 `100`，`planned` 应为 `0`，`skipped` 不计入 dashboard 总完成度。dashboard 以阶段表计算进度，不从正文推断。

package/templates-zh-CN/reference/adversarial-review-standard.md

@@ -0,0 +1,89 @@
+# 对抗性审查标准
+
+## 职责
+
+本标准规定 reviewer、只读 subagent、外部 agent 或人工审查者如何在任务收口前挑战方案、实现、证据和残余风险。审查报告不是进度记录，也不是 walkthrough；它的作用是把“还有没有会改变交付判断的问题”说清楚。
+
+审查报告默认写入：
+
+```text
+docs/09-PLANNING/TASKS/<YYYY-MM-DD-任务名>/review.md
+```
+
+审查路由由 `review-routing-standard.md` 决定；本文件只规定审查报告怎么写、什么结论可以收口。
+
+## 必须触发的场景
+
+- 长程任务合同包含 review loop。
+- 任务触及架构、数据、安全、权限、部署、迁移、CI/CD 或跨模块契约。
+- release 前验证、live smoke、browser inspection、回归 gate 或 required checks 暴露过问题。
+- 使用 reviewer agent、subagent、外部 agent 或人工审查者。
+- 用户明确要求审查、对抗性审查或独立复核。
+
+## 审查核心问题
+
+每轮审查都必须回答：
+
+> 你对当前方案、实现、证据和收口策略是否有 100% 信心？如果没有，列出所有可能改变交付判断的漏洞，给出修复或路由建议，并继续循环，直到没有 open material findings。
+
+这里的 100% 信心只表示在当前目标、范围和证据下没有发现阻塞性漏洞；不能用主观感觉替代证据。
+
+## 报告字段
+
+| 字段 | 中文说明 | 要求 |
+| --- | --- | --- |
+| `Reviewer Identity` | 审查者身份 | 写明 reviewer 类型、模型或人员、是否只读、审查时间。 |
+| `Review Scope` | 审查范围 | 写明审查对象、目标、out of scope、输入材料。 |
+| `Confidence Challenge` | 信心挑战 | 回答 100% 信心问题，列出挑战过程和循环次数。 |
+| `Evidence Checked` | 已核验证据 | 列出实际看过的文件、命令、日志、截图、PR、CI 结果。 |
+| `Material Findings` | 重要发现 | 记录 P0/P1 以及会改变 stop condition 的 P2。 |
+| `Required Checks` | 必需检查 | 标明哪些检查必须重跑，哪些检查可 residual。 |
+| `Final Confidence Basis` | 最终信心依据 | 说明为什么可以或不可以收口。 |
+| `Residual` | 残余风险 | 写明已接受残余、owner、后续路由和不阻塞理由。 |
+
+## 严重级别
+
+| 级别 | 含义 | 收口规则 |
+| --- | --- | --- |
+| P0 | 数据损坏、安全事故、生产不可用、错误发布 | 必须停下，不能收口。 |
+| P1 | 核心路径、关键契约或主要验收标准被破坏 | 必须修复并重跑证据。 |
+| P2 | 明确回归、维护风险或验证不足 | 必须修复，或写成 `accepted-risk` 并路由。 |
+| P3 | 质量建议、可读性问题、非阻塞改进 | 可作为后续任务，不阻塞本轮。 |
+
+`material findings` 指 P0/P1，以及任何会改变 stop condition 的 P2。
+
+## 发现状态
+
+`review.md` 的 `Disposition` 只允许使用：
+
+- `open`
+- `mitigated`
+- `closed`
+- `deferred`
+- `accepted-risk`
+- `not-reproducible`
+- `out-of-scope`
+
+`accepted-risk` 必须写明为什么不阻塞本轮目标，并路由到 task、SSoT、Regression SSoT、Lessons SSoT 或后续 PR。
+
+## 无发现结论
+
+没有 material findings 时，也必须显式写：
+
+```text
+No material findings. 当前证据覆盖了本轮 stop condition，未发现阻塞收口的问题。
+```
+
+如果证据不足，不能写无发现；应写成 residual 或 blocked。
+
+## 收口门槛
+
+任务不能在以下状态收口：
+
+- 存在 `open` 的 P0/P1 finding。
+- material P2 没有修复，也没有 `accepted-risk` 和后续路由。
+- 长程任务合同要求 review loop，但没有 `review.md`。
+- 缺少 `Confidence Challenge` 或 `Final Confidence Basis`。
+- 缺少 `Evidence Checked`，或证据只来自聊天记录。
+- finding 修复后没有重跑对应证据。
+- walkthrough、Closeout SSoT 或 Harness Ledger 没有引用审查结果或跳过原因。

package/templates-zh-CN/reference/ci-cd-standard.md

@@ -0,0 +1,72 @@
+# CI/CD 标准
+
+## 职责
+
+本标准定义项目的 CI/CD 入口、required checks、密钥边界、发布路径和证据状态。它的目标不是描述理想流水线，而是让 agent 能判断：本轮改动需要跑哪些检查、哪些检查已经验证、哪些仍是 residual。
+
+## 项目 CI 画像
+
+| 项 | 项目约定 |
+| --- | --- |
+| CI 平台 | GitHub Actions / GitLab CI / 本地脚本 / 其他 |
+| 主要运行时 | Node / Python / Go / Rust / Java / mixed / 其他 |
+| 包管理器 | 项目实际使用的工具 |
+| 安装命令 | 例如 `npm ci`、`pnpm install`、`uv sync` |
+| lint 命令 | 项目标准命令 |
+| typecheck 命令 | 如适用，写明命令；不适用时写 `n/a` 和原因 |
+| test 命令 | 单元、集成或项目默认测试 |
+| build 命令 | 构建或打包命令 |
+| smoke / regression 命令 | 本地冒烟、浏览器检查、live smoke 或回归入口 |
+| 缓存策略 | 依赖、构建产物、浏览器二进制等缓存边界 |
+| 必需密钥 | 只写变量名和用途，不写密钥值 |
+| 不支持的检查 | 写明原因、owner 和 residual |
+
+## 工作流登记
+
+| 工作流 | 路径 | 触发条件 | 必需 job | 证据 |
+| --- | --- | --- | --- | --- |
+| PR 检查 | `.github/workflows/...` | pull request | lint / typecheck / test / build | workflow run 或本地等价命令 |
+| 主干检查 | `.github/workflows/...` | default branch push | 项目约定 | workflow run |
+| 发布检查 | `.github/workflows/...` | tag / release / manual dispatch | build / smoke / deploy | release log |
+
+如果项目暂时只有本地检查，也要写清本地命令、谁负责执行、何时升级为 CI。
+
+## 必需检查
+
+| 检查 | 命令或 job | 是否必需 | 何时运行 | 证据要求 | residual 规则 |
+| --- | --- | --- | --- | --- | --- |
+| lint | 项目命令或 CI job | yes/no | PR 前或收口前 | 通过日志或 workflow run | 失败必须修复或写 owner |
+| typecheck | 项目命令或 CI job | yes/no | 类型相关改动后 | 通过日志 | 不适用需说明 |
+| build | 项目命令或 CI job | yes/no | 构建面受影响时 | 通过日志 | 失败不能发布 |
+| test | 项目命令或 CI job | yes/no | 非平凡改动后 | 测试结果 | flaky 需记录 |
+| smoke / regression | 项目命令或手工脚本 | yes/no | merge、release 或关键面变更 | 截图、日志、trace 或回归记录 | residual 路由到 Regression SSoT |
+
+## 发布与回滚
+
+| 项 | 项目约定 |
+| --- | --- |
+| 发布触发 | tag、release branch、manual dispatch、外部平台 |
+| 发布环境 | staging / production / local-only |
+| 审批要求 | 自动、人工审批、owner approval |
+| 回滚路径 | revert、重新部署旧版本、平台 rollback |
+| 签名与凭证边界 | 密钥来源、可见范围、谁有权限 |
+| 不在本轮范围内的发布能力 | 写明原因和后续 owner |
+
+## 状态枚举
+
+CI/CD 相关状态只使用：
+
+- `designed`：规则已设计，但没有落地。
+- `implemented`：脚本或 workflow 已存在，但未验证。
+- `verified`：已用当前证据验证通过。
+- `blocked-with-owner`：有阻塞，且已写明 owner。
+- `n/a`：本项目或本轮不适用，并已说明原因。
+
+禁止把 `designed` 或 `implemented` 写成 `verified`。
+
+## 收口要求
+
+- PR 或 walkthrough 必须列出本轮实际运行的 required checks。
+- 跳过 required check 时，必须写 residual、owner 和不阻塞理由。
+- 发布相关改动必须说明 release trigger、credential boundary 和 rollback path。
+- CI/CD 标准变化必须同步 `repo-governance-standard.md`、Regression SSoT 或 Harness Ledger。

package/templates-zh-CN/reference/delivery-operating-model-standard.md

@@ -0,0 +1,79 @@
+# 交付运行模型标准
+
+## 职责
+
+本标准用于在实现开始前选定交付模型，明确规划 owner、集成 owner、发布 owner、共享文件治理和多 agent 协作边界。没有运行模型，agent 容易把 solo 任务、多模块并行、多仓协作和阶段式交付混在一起，导致计划、审查和 merge 顺序不可控。
+
+## 运行模型画像
+
+| 项 | 项目约定 |
+| --- | --- |
+| 交付模型 | solo orchestrator / team feature lead / split-repo contract / program multi-repo / waterfall stage gate / kanban continuous |
+| 团队形态 | 单 agent、主 agent + reviewer、coordinator + workers、多人团队 |
+| 仓库拓扑 | 单仓、monorepo、多仓、前后端分离、库 + 应用 |
+| 主要规划 owner | 负责维护 task plan、Delivery SSoT、Module Registry 的角色 |
+| 集成 owner | 负责 merge、冲突解决、最终 gates 的角色 |
+| 发布 owner | 负责 release、环境确认、回滚判断的角色 |
+| agent 可见范围 | 哪些目录、文档、外部系统可读；哪些必须先确认 |
+
+## 任务拆分规则
+
+| 层级 | 负责人 | 主要产物 | 规则 |
+| --- | --- | --- | --- |
+| 路线图 | product / tech lead / owner | roadmap、release plan | 只放阶段目标，不替代任务计划。 |
+| 功能块 | coordinator / feature lead | `docs/09-PLANNING/Delivery-SSoT.md` 或功能 SSoT | 标明 owner、依赖、集成顺序。 |
+| 任务 | task owner | `docs/09-PLANNING/TASKS/<task>/task_plan.md` | 每个任务有目标、范围、证据和 stop condition。 |
+| 审查 | reviewer / subagent / human | `review.md` 或 PR review | 按审查路由执行，不只留在聊天里。 |
+| 集成 | coordinator / maintainer | PR、integration branch、release branch | 由集成 owner 决定 merge 顺序和最终 gates。 |
+
+## 已选模型合同
+
+项目必须写清：
+
+- 为什么当前交付模型适合本项目。
+- feature block 如何分配，谁可以改状态。
+- 共享文件如何加锁、排队或串行修改。
+- merge 顺序如何决定，冲突由谁处理。
+- 跨仓接口怎么变更，schema 或 API 的 source of truth 在哪里。
+- reviewer 与 worker 的边界是什么。
+- agent 可以读取哪些上下文，哪些上下文必须由 owner 提供。
+
+## 交付单一事实源要求
+
+以下任一条件成立时，必须维护 `docs/09-PLANNING/Delivery-SSoT.md`：
+
+- 多人或多 agent 并行开发。
+- 多仓或前后端分离协作。
+- 存在共享文件、跨模块契约或 release branch。
+- 用户要求按阶段、模块或 feature block 管理交付。
+
+不需要 Delivery SSoT 时，也要在任务计划里写明原因。
+
+## 跨仓接口合同
+
+跨仓、前后端或服务间协作必须记录：
+
+| 项 | 要求 |
+| --- | --- |
+| API / schema source of truth | OpenAPI、GraphQL schema、protobuf、类型定义或文档路径。 |
+| 请求与响应示例 | 至少覆盖成功、权限失败、校验失败。 |
+| 错误语义 | 错误码、HTTP status、用户可见文案边界。 |
+| 兼容策略 | breaking change、向后兼容、灰度策略。 |
+| mock / stub 策略 | 本地开发和测试替身如何保持同步。 |
+| breaking-change owner | 谁批准破坏性变更。 |
+| 前端验证 | UI、e2e、contract test 或 smoke。 |
+| 后端验证 | unit、integration、contract test、live smoke。 |
+
+## 证据状态
+
+| 项 | 状态 | 证据 | residual |
+| --- | --- | --- | --- |
+| 交付模型已选定 | `designed` / `implemented` / `verified` / `blocked-with-owner` | 任务计划或标准路径 | 未决项 |
+| 规划 owner 已明确 | 同上 | Delivery SSoT 或 task plan | 未决项 |
+| 集成 owner 已明确 | 同上 | PR、progress 或 Delivery SSoT | 未决项 |
+| feature block 分配规则 | 同上 | Delivery SSoT | 未决项 |
+| 共享文件和跨仓冲突规则 | 同上 | repo governance、worktree 标准或任务计划 | 未决项 |
+
+## 收口要求
+
+非 solo 任务收口前必须确认：Delivery SSoT、Module Registry、worker handoff、review、Regression SSoT 和 Harness Ledger 是否都已更新；不能只看单个 worker 的本地结果就宣布完成。

package/templates-zh-CN/reference/docs-library-standard.md

@@ -0,0 +1,59 @@
+# 文档库标准
+
+## 职责
+
+本标准定义 `docs/` 文档库的目录、命名、归档和引用规则。文档库服务于 agent 执行，不是资料堆；每个文件都应有明确职责、当前事实和可追溯证据。
+
+## 目录职责
+
+| 位置 | 职责 |
+| --- | --- |
+| `docs/Harness-Ledger.md` | 全局上下文维护总账，记录非平凡任务是否完成计划、审查、回归、Lessons 和收口回写。 |
+| `docs/01-GOVERNANCE/` | Lessons SSoT、经验详情、治理记录、归档。 |
+| `docs/03-ARCHITECTURE/` | ADR、架构设计、接口决策、关键技术方案。 |
+| `docs/05-TEST-QA/` | Regression SSoT、Cadence Ledger、测试策略和回归证据索引。 |
+| `docs/09-PLANNING/` | Delivery SSoT、Module Registry、任务目录、模块计划。 |
+| `docs/09-PLANNING/TASKS/` | 每个任务一个目录，包含 task plan、progress、findings、review。 |
+| `docs/10-WALKTHROUGH/` | 收口记录和 Closeout SSoT。 |
+| `docs/11-REFERENCE/` | agent 按需加载的标准文件，控制行为而不是记录流水账。 |
+| `docs/99-TMP/` | 临时材料，定期清理，不作为长期事实来源。 |
+
+## 命名规则
+
+- 目录可使用编号前缀，例如 `09-PLANNING`、`11-REFERENCE`。
+- 标准文件使用 kebab-case，例如 `testing-standard.md`。
+- 时序文档使用日期前缀，例如 `2026-05-19-runtime-cleanup-walkthrough.md`。
+- 模板目录或模板文件用 `_` 前缀，例如 `_task-template/`。
+- ID、状态枚举、命令名、schema 字段可保留英文；可见标题和说明优先中文。
+
+## 文档类型
+
+| 类型 | 推荐位置 | 要求 |
+| --- | --- | --- |
+| 任务计划 | `09-PLANNING/TASKS/<task>/task_plan.md` | 写目标、范围、证据、stop condition。 |
+| 进度记录 | `09-PLANNING/TASKS/<task>/progress.md` | 记录阶段状态、阻塞、决策和验证。 |
+| 研究发现 | `09-PLANNING/TASKS/<task>/findings.md` | 记录调查证据，不替代审查报告。 |
+| 审查报告 | `09-PLANNING/TASKS/<task>/review.md` | 记录 Confidence Challenge、material findings、evidence、residual。 |
+| 收口记录 | `10-WALKTHROUGH/<date>-<name>.md` | 给下一轮 agent 的可追溯交接。 |
+| Closeout SSoT | `10-WALKTHROUGH/Closeout-SSoT.md` | closed task 的 walkthrough 路径和跳过原因索引。 |
+| Regression SSoT | `05-TEST-QA/Regression-SSoT.md` | 管回归 surface、evidence depth、residual。 |
+| Harness Ledger | `Harness-Ledger.md` | 管上下文维护合规性，不复制业务事实。 |
+| Reference 标准 | `11-REFERENCE/*.md` | 管长期规则，避免写成任务日志。 |
+
+## 归档规则
+
+- 会持续增长的目录必须有同级 `_archive/`。
+- 活跃文件只保留当前事实；历史事实移入 `_archive/`，不能无限追加在活跃表底部。
+- 归档不删除原始 ID，不破坏 task plan、walkthrough、SSoT、Ledger 之间的引用。
+- 活跃文件必须留下归档指针，说明历史记录在哪里。
+- `review.md` 留在对应任务目录，不移动到 walkthrough 或根目录。
+- `docs/Harness-Ledger.md` 固定保留在 docs 根目录，是根目录过程文件禁令的唯一例外。
+- `docs/99-TMP/` 下超过 7 天未更新的文件应清理或迁移到正式位置。
+
+## 写作原则
+
+1. 文档面向后续 agent 执行，必须可操作、可检索、可验证。
+2. 标准文件写长期规则；任务文件写本轮事实；walkthrough 写交接结论。
+3. 证据用路径、命令、日志、截图、PR、CI run 引用，不依赖聊天记录。
+4. 表格用于状态和路由；段落用于解释判断和边界。
+5. 更新 reference 或 template 时，必须在 Harness Ledger 记录本次上下文维护。

package/templates-zh-CN/reference/engineering-standard.md

@@ -0,0 +1,80 @@
+# 工程标准
+
+## 职责
+
+本标准定义项目的工程边界、模块组织、代码质量、安全约束和测试期待。它用于帮助 agent 判断“什么改法符合本仓库”，而不是重新发明一套通用最佳实践。
+
+## 架构原则
+
+项目应维护以下工程约束：
+
+| 约束 | 项目约定 | 验证方式 |
+| --- | --- | --- |
+| 分层边界 | 例如 adapter / core / runtime，或前端 / 服务 / 数据层 | 架构文档、依赖检查、测试 |
+| 依赖方向 | 低层不反向依赖高层；业务核心不依赖具体外部平台 | import 检查、代码审查 |
+| 接口边界 | 外部依赖通过接口、client、adapter 或 service 封装 | 单元测试、mock、contract test |
+| 状态来源 | SSoT、数据库、配置、缓存各自职责明确 | 代码路径和回归证据 |
+| 失败语义 | 错误类型、日志、用户可见反馈一致 | 测试、日志检查、smoke |
+
+## 代码风格
+
+| 项 | 项目约定 |
+| --- | --- |
+| 主要语言 | TypeScript / Python / Go / Rust / Java / mixed / 其他 |
+| 格式化工具 | Prettier / Ruff / gofmt / rustfmt / 其他 |
+| lint 工具 | ESLint / Ruff / golangci-lint / 其他 |
+| 类型检查 | tsc / mypy / pyright / 其他 |
+| 代码生成 | 生成命令、生成物是否提交、禁止手改范围 |
+| 公共 API 变更 | 需要更新的 schema、文档、测试和兼容说明 |
+
+## 模块组织
+
+项目必须在本标准或架构文档中写清：
+
+- 主要目录的职责。
+- 哪些目录是业务核心，哪些是 adapter、runtime、工具或测试。
+- 共享文件的 owner 和修改顺序。
+- 新模块创建规则：命名、入口、测试、文档、导出方式。
+- 不允许跨越的依赖边界。
+
+## 命名规则
+
+| 类型 | 规则 | 备注 |
+| --- | --- | --- |
+| 文件名 | 遵循项目既有风格，例如 kebab-case、camelCase 或 PascalCase | 不因单次任务混用风格。 |
+| 类型 / 类 | 遵循语言惯例，例如 PascalCase | 公共类型需语义清晰。 |
+| 函数 | 描述动作和结果 | 避免 `handleThing` 这类无上下文命名。 |
+| 常量 | 遵循项目惯例，例如 UPPER_SNAKE_CASE | 只用于真正常量。 |
+| 测试用例 | 描述条件和期望 | 失败时应能定位问题。 |
+
+## 错误处理与日志
+
+- 用户可见错误、系统日志、调试日志分层处理。
+- 不吞掉异常；确实降级时必须有可观察证据。
+- 日志不得输出密钥、token、个人敏感信息或完整凭证。
+- 外部服务错误要保留可诊断上下文，例如 request id、status、错误类型。
+- 重试、超时、幂等边界必须在代码或文档中明确。
+
+## 安全约束
+
+1. 不在代码、测试快照、文档或示例中硬编码密钥。
+2. 敏感配置通过环境变量、密钥管理或部署平台注入。
+3. 权限、数据迁移、删除、支付、发布相关改动必须触发审查。
+4. 生产数据操作必须有回滚或恢复路径。
+5. 新增依赖要考虑许可证、维护状态、供应链风险和构建影响。
+
+## 性能与可靠性
+
+- 明确关键路径的延迟、吞吐、资源使用或包体约束。
+- 大批量任务要有分页、限流、重试和中断恢复策略。
+- 前端交互要避免明显布局抖动、阻塞渲染和无反馈等待。
+- 后端任务要记录运行状态、失败原因和可重试边界。
+
+## 收口要求
+
+非平凡工程改动完成前必须提供：
+
+- 受影响模块和边界说明。
+- 对应测试、build、smoke 或回归证据。
+- 对架构、依赖、配置、schema 或安全边界的影响判断。
+- 如存在 residual，写明 owner、后续路径和为什么不阻塞本轮目标。