create-harness-vibe-coding 0.1.0

package/templates/common/docs/README.md

@@ -0,0 +1,112 @@
+# {{projectName}} — 文档入口
+
+> **定位**：给人和 coding agent 共用的项目地图。`AGENTS.md` 负责让 agent 先读 `CLAUDE.md`，再从这里进入项目事实源。
+>
+> **原则**：短入口 + 分主题文档。不要把所有规则塞进 `CLAUDE.md` 或 `AGENTS.md`。
+
+---
+
+## 0-1 项目必经流程
+
+从零开始做一个项目时，必须按下面顺序产出文档。前一阶段没有最低可用结论，不进入后一阶段。
+
+| 顺序 | 产物 | 必须回答的问题 | 完成标准 |
+| --- | --- | --- | --- |
+| 1 | [research/scaffolds.md](research/scaffolds.md) | 别人怎么做？有哪些候选模板、框架、约束？为什么采用/不采用？ | 至少 3 个参考物；每个写清 Purpose / Strength / Weakness / Decision |
+| 2 | [research/PRD.md](research/PRD.md) | 这个 MVP 到底解决什么？明确不做什么？怎么验收？ | 一页内；包含 MVP、Non-goals、可验证验收标准 |
+| 3 | [harness/architecture.md](harness/architecture.md) | 系统分几层？组件边界是什么？harness 能做什么、不能做什么？ | 分层依赖、核心组件、不可违反约束、关键决策都写清 |
+| 4 | [domain/ports.md](domain/ports.md) | 层与层之间用什么合同通信？错误和幂等语义是什么？ | 每个端口有前置条件、后置条件、错误语义、已知实现 |
+| 5 | [harness/data-flow.md](harness/data-flow.md) | 正常路径和失败路径怎么跑？调用方看到什么？ | 至少 1 条核心流程；每个失败点都有系统行为和恢复方式 |
+| 6 | [harness/state-machines.md](harness/state-machines.md) | 哪些组件有状态？哪些转移合法/非法？ | 每个有状态组件有状态枚举、转移表、非法转移说明 |
+| 7 | [harness/agent-workflow.md](harness/agent-workflow.md) | agent 怎么分工、TDD、验证和闭环？ | Feature doc 模板、subagent 分工、write set、完成标准写清 |
+| 8 | tests + implementation | 设计是否被代码证明？ | 最小垂直切片可运行；测试覆盖核心成功/失败路径 |
+
+**硬门槛**：
+- 如果相关文档仍然只剩 `{{...}}` 占位符，不要声称架构已定稿。
+- **最小可开始编码的文档集**：`research/PRD.md` + `harness/architecture.md` + 至少 1 个已填好的端口合同。达到这个门槛后可以开始最小垂直切片，但必须在 feature doc 或测试里记录尚未补齐的 `data-flow.md` / `state-machines.md` 风险。
+- 如果新增或修改架构边界，必须同步更新对应文档和测试。
+- 如果实现需要超过一个短会话，先按 [features/_template.md](features/_template.md) 开 feature doc；feature doc 必须包含目的、边界、任务、验证、决策记录。
+
+## 每份文档的完成标准
+
+| 文档 | 最低完成标准 | 可以暂缺 |
+| --- | --- | --- |
+| `research/scaffolds.md` | 至少 3 个参考物；每个有 Purpose / Strength / Weakness / Decision；有最终决策 | 被放弃方案可后补 |
+| `research/PRD.md` | Why、MVP、Non-goals、决策优先级、验收标准都不是占位符 | 非功能性指标可先写 MVP 级目标 |
+| `harness/architecture.md` | 分层依赖、核心组件、至少 1 条 ADR、不可违反约束 | Runner 变体可在只有一种 runner 时写"暂无" |
+| `domain/ports.md` | 至少 1 个端口有前置条件、后置条件、错误语义、幂等性、已知实现 | 后续端口可随 feature 增量补 |
+| `harness/data-flow.md` | 至少 1 条核心流程有正常路径 + 失败路径 | 次要流程可后补 |
+| `harness/state-machines.md` | 已有有状态组件都有状态枚举和转移表 | 无状态组件不用写 |
+| `harness/agent-workflow.md` | 开 feature doc、write set、验证、关闭标准明确 | subagent 角色可按需要扩展 |
+| `features/*.md` | Requirements / Design / Tasks / Verification 四段闭环 | 小修可走快车道并说明原因 |
+
+---
+
+## Harness 边界
+
+当前模板采用 `interfaces -> harness -> application -> domain` 加 `infrastructure` 适配器的分层思路。这里的 `domain` 是任意业务域：数据分析、文档处理、代码修复、运营自动化等都可以挂在同一个 harness 底座上。
+
+| 层 | 负责 | 不负责 |
+| --- | --- | --- |
+| `interfaces/` | CLI / API / UI 入口 | 业务规则、数据源细节 |
+| `harness/` | 运行外壳、调度、安全门、审计、可观测性、失败控制 | 领域业务规则、领域决策、适配器实现细节 |
+| `application/` | 用例编排，把领域端口组合成业务行为 | 具体外部服务实现 |
+| `domain/` | 业务对象、业务不变量、端口协议 | 导入 harness / infrastructure / interfaces |
+| `infrastructure/` | 文件系统、数据库、外部 API、模型服务等端口实现 | 定义业务合同 |
+
+判断一段代码该不该在 `harness/`：如果它是在"运行期间保护、记录、调度、恢复系统"，放 harness；如果它是在"决定某个业务动作是否应该发生、代表什么领域含义"，放 application/domain。
+
+---
+
+## 文档地图
+
+```text
+docs/
+├── README.md                       ← 你在这里
+├── features/
+│   └── _template.md                ← 单功能实现文档模板（Kiro-lite）
+├── harness/
+│   ├── agent-workflow.md           ← agent 分工、TDD、闭环、write set 规则
+│   ├── architecture.md             ← 组件全景、分层规则、关键设计决策
+│   ├── data-flow.md                ← 端到端事件流转：正常路径 + 异常路径
+│   └── state-machines.md           ← 有状态组件的状态转移图和转移表
+├── domain/
+│   └── ports.md                    ← 跨层接口契约：前置/后置、错误语义
+└── research/
+    ├── PRD.md                      ← 一页 MVP 边界和验收标准模板
+    └── scaffolds.md                ← 调研结论、参考模板、技术选型理由
+```
+
+---
+
+## 阅读顺序
+
+| 角色 | 先读 | 然后读 |
+| --- | --- | --- |
+| 新加入开发者 | [research/PRD.md](research/PRD.md) | [harness/architecture.md](harness/architecture.md) |
+| 实现者 | [harness/agent-workflow.md](harness/agent-workflow.md) | [features/_template.md](features/_template.md) |
+| 审查者 | [harness/state-machines.md](harness/state-machines.md) | tests |
+| 架构维护者 | [research/scaffolds.md](research/scaffolds.md) | [harness/architecture.md](harness/architecture.md) |
+
+---
+
+## 维护规则
+
+- 代码变更影响架构：更新 `harness/architecture.md`。
+- 新增跨层接口：更新 `domain/ports.md`。
+- 新增流程或失败路径：更新 `harness/data-flow.md`。
+- 新增有状态组件：更新 `harness/state-machines.md`。
+- 新增外部依赖、模板、框架选择：更新 `research/scaffolds.md`。
+- 新增非平凡功能：复制 `features/_template.md` 创建 feature doc，并按 `harness/agent-workflow.md` 闭环。
+- 文档规则反复被 agent 忽略：不要继续加长入口文件，把规则变成测试、lint 或更具体的模板。
+
+---
+
+## 外部参考
+
+- OpenAI, Harness Engineering: 短 `AGENTS.md` 作为目录，`docs/` 作为事实源；架构边界用测试/lint 机械化验证。
+- Anthropic, Claude Code Best Practices: `CLAUDE.md` 保持短且可维护，可用 `@docs/...` 引入项目文档。
+- OpenAI, PLANS.md / ExecPlans: 复杂任务使用自包含、可验证、可恢复的执行计划。
+- GitHub Spec Kit / Kiro Specs: 借用 requirements -> design -> tasks -> verification 的结构。
+- Anthropic, Building Effective Agents: agent loop 要基于环境反馈、明确停止条件和人工检查点。
+- arc42 / C4 / ADR / ARCHITECTURE.md: 分别提供架构章节、静态结构视图、决策记录和轻量代码地图。

package/templates/common/docs/domain/ports.md

@@ -0,0 +1,73 @@
+# 端口协议 — {{projectName}}
+
+> **职责**：定义跨层接口契约。这是分层架构的"法律合同"。每个端口不仅写签名，还写前置条件、后置条件、错误语义。
+>
+> **原则**：端口文档 != API 参考文档。它是一个合同（contract），指定调用方义务和实现方保证。
+>
+> 哲学来源：Bertrand Meyer 的 Design by Contract (Eiffel) + Alistair Cockburn 的六边形架构端口文档。
+
+---
+
+## 1. 端口分类
+
+### 1.1 驱动端口（Inbound — 外部调用应用）
+
+| 端口 | 定义位置 | 用途 |
+| --- | --- | --- |
+| `{{INBOUND_PORT_1}}` | `{{LOCATION}}` | {{DESCRIPTION}} |
+
+### 1.2 被驱动端口（Outbound — 应用调用外部）
+
+| 端口 | 定义位置 | 用途 |
+| --- | --- | --- |
+| `{{OUTBOUND_PORT_1}}` | `{{LOCATION}}` | {{DESCRIPTION}} |
+
+---
+
+## 2. 端口定义模板
+
+每个端口按以下格式填写：
+
+- **类别**：驱动 / 被驱动
+- **定义位置**：`{{FILE_PATH}}`
+- **协议类**：`{{CLASS_OR_INTERFACE}}`
+
+### 用途
+
+{{WHAT_THIS_PORT_DOES}}
+
+### 方法
+
+**前置条件**（调用方必须保证）：
+- {{PRECONDITION_1}}
+- {{PRECONDITION_2}}
+
+**后置条件**（实现方保证）：
+- {{POSTCONDITION_1}}
+- {{POSTCONDITION_2}}
+
+**错误语义**：
+
+| 异常类型 | 触发条件 | 调用方应 |
+| --- | --- | --- |
+| `{{EXCEPTION_TYPE}}` | {{CONDITION}} | {{CALLER_ACTION}} |
+
+**幂等性**：{{YES_NO_AND_DETAILS}}
+
+### 已知实现
+
+| 适配器 | 位置 | 用途 |
+| --- | --- | --- |
+| `{{ADAPTER_NAME}}` | `{{LOCATION}}` | {{PURPOSE}} |
+
+---
+
+## 3. 跨端口不变量
+
+- {{INVARIANT_1}}
+- {{INVARIANT_2}}
+- 新增端口必须定义在 `domain/ports` 中，适配器放在 `infrastructure/`。
+
+---
+
+> **提示**：当前 ports.md 是模板。请根据你的项目领域替换 `{{...}}` 占位符。参考 `docs/harness/data-flow.md` 了解端口如何被编排。

package/templates/common/docs/features/_template.md

@@ -0,0 +1,135 @@
+# {{FEATURE_NAME}}
+
+> **状态**：Draft / In Progress / Blocked / Done
+> **创建日期**：{{YYYY-MM-DD}}
+> **负责人**：{{OWNER_OR_AGENT}}
+> **关联文档**：{{PRD_OR_ARCH_DOC_LINKS}}
+
+---
+
+## 1. Requirements
+
+### 1.1 背景
+
+{{WHY_THIS_FEATURE_EXISTS}}
+
+### 1.2 目标
+
+- {{GOAL_1}}
+- {{GOAL_2}}
+
+### 1.3 非目标
+
+- {{NON_GOAL_1}}
+- {{NON_GOAL_2}}
+
+### 1.4 验收标准
+
+- [ ] {{ACCEPTANCE_CRITERION_1}}
+- [ ] {{ACCEPTANCE_CRITERION_2}}
+- [ ] {{ACCEPTANCE_CRITERION_3}}
+
+---
+
+## 2. Design
+
+### 2.1 影响范围
+
+| 区域 | 是否影响 | 说明 |
+| --- | --- | --- |
+| `harness/architecture.md` | {{YES_NO}} | {{NOTE}} |
+| `domain/ports.md` | {{YES_NO}} | {{NOTE}} |
+| `harness/data-flow.md` | {{YES_NO}} | {{NOTE}} |
+| `harness/state-machines.md` | {{YES_NO}} | {{NOTE}} |
+| tests | {{YES_NO}} | {{NOTE}} |
+
+### 2.2 Allowed Write Set
+
+- `{{PATH_OR_GLOB_1}}`
+- `{{PATH_OR_GLOB_2}}`
+
+### 2.3 Forbidden Scope
+
+- `{{PATH_OR_BEHAVIOR_1}}`
+- `{{PATH_OR_BEHAVIOR_2}}`
+
+### 2.4 方案
+
+#### 候选方案
+
+| 方案 | 优点 | 缺点 | 结论 |
+| --- | --- | --- | --- |
+| {{OPTION_A}} | {{PROS_A}} | {{CONS_A}} | {{ACCEPT_REJECT}} |
+| {{OPTION_B}} | {{PROS_B}} | {{CONS_B}} | {{ACCEPT_REJECT}} |
+
+#### 选择理由
+
+{{SELECTED_DESIGN_AND_RATIONALE}}
+
+### 2.5 边界条件
+
+- {{EDGE_CASE_1}} -> {{EXPECTED_BEHAVIOR_1}}
+- {{EDGE_CASE_2}} -> {{EXPECTED_BEHAVIOR_2}}
+
+---
+
+## 3. Tasks
+
+> 每个 task 必须有验证方式。需要 subagent 时，先写清角色和 write set。
+
+| # | Task | Owner | Write Set | Verify |
+| --- | --- | --- | --- | --- |
+| 1 | {{WRITE_FAILING_TEST_OR_DOC_CHECK}} | {{OWNER}} | `{{PATH}}` | `{{COMMAND_OR_CHECK}}` |
+| 2 | {{IMPLEMENT_MINIMAL_CHANGE}} | {{OWNER}} | `{{PATH}}` | `{{COMMAND_OR_CHECK}}` |
+| 3 | {{SYNC_DOCS_OR_BOUNDARIES}} | {{OWNER}} | `{{PATH}}` | `{{COMMAND_OR_CHECK}}` |
+
+### Subagent Plan
+
+| Role | Needed? | Scope |
+| --- | --- | --- |
+| Explorer | {{YES_NO}} | {{READ_ONLY_SCOPE}} |
+| Test Writer | {{YES_NO}} | {{TEST_WRITE_SET}} |
+| Implementer | {{YES_NO}} | {{IMPLEMENTATION_WRITE_SET}} |
+| Reviewer | {{YES_NO}} | {{REVIEW_SCOPE}} |
+| Verifier | {{YES_NO}} | {{VERIFY_COMMANDS}} |
+
+---
+
+## 4. Verification
+
+### 4.1 Test Results
+
+| Command | Result | Notes |
+| --- | --- | --- |
+| `{{TEST_COMMAND}}` | {{PASS_FAIL_NOT_RUN}} | {{NOTES}} |
+| `{{OTHER_COMMAND}}` | {{PASS_FAIL_NOT_RUN}} | {{NOTES}} |
+
+### 4.2 Review Findings
+
+- {{FINDING_OR_NONE}}
+
+### 4.3 Docs Sync
+
+- [ ] `harness/architecture.md`
+- [ ] `domain/ports.md`
+- [ ] `harness/data-flow.md`
+- [ ] `harness/state-machines.md`
+- [ ] `research/scaffolds.md`
+- [ ] Not needed because {{REASON}}
+
+### 4.4 Decision Log
+
+| Date | Decision | Reason |
+| --- | --- | --- |
+| {{YYYY-MM-DD}} | {{DECISION}} | {{REASON}} |
+
+### 4.5 Closeout
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Tests or manual verification recorded.
+- [ ] Boundary impact documented.
+- [ ] Remaining risks listed or explicitly none.
+- [ ] If docs/code/tests conflicted, Decision Log records how it was resolved.
+
+Remaining risks:
+- {{RISK_OR_NONE}}

package/templates/common/docs/harness/agent-workflow.md

@@ -0,0 +1,145 @@
+# Agent Workflow Harness
+
+> **职责**：约束 agent 如何实现一个功能。它不是 runtime 代码架构，而是 engineering harness：防止 AI 跳过需求、乱改边界、缺测试、没有闭环。
+>
+> **原则**：小任务轻流程，大任务有文档；用测试和边界检查约束 agent，而不是靠长提示词。
+
+---
+
+## 1. 什么时候必须开 Feature Doc
+
+使用 [../features/_template.md](../features/_template.md) 创建一个新的 `docs/features/{{FEATURE_SLUG}}.md`。
+
+必须开文档：
+- 新增功能或用户可见行为。
+- 修改跨层契约、端口、状态机、数据流或权限规则。
+- 影响多个模块，或预计超过一个短会话。
+- 修复边界不清的 bug，需要先定义期望行为。
+- 需要 subagents 分工、TDD 或人工审批。
+
+可以不开文档：
+- 拼写、链接、注释等纯文档小修。
+- 单测试断言或单行安全修复，且边界完全清楚。
+- 只读调查或一次性命令输出。
+
+如果不确定，开一个短 feature doc。短文档比隐含假设便宜。
+
+---
+
+## 2. Kiro-lite 流程
+
+每个非平凡功能按一个文件走完四段，不默认拆多个文件。
+
+1. **Requirements**：写清目标、非目标、验收标准。
+2. **Design**：写清影响范围、允许修改文件、不允许修改文件、接口/状态/数据流变化。
+3. **Tasks**：拆成可验证任务，每个任务有 owner、write set、验证命令。
+4. **Verification**：记录测试结果、边界检查、文档同步、剩余风险。
+
+只有当 feature doc 超过约 200 行，或任务需要多人/多 agent 长时间并行时，才升级为目录：
+
+```text
+docs/features/{{FEATURE_SLUG}}/
+├── requirements.md
+├── design.md
+├── tasks.md
+└── verification.md
+```
+
+---
+
+## 3. Subagent 分工
+
+Subagent 是分工工具，不是责任转移。主 agent 负责最终集成、验证和解释。
+
+| 角色 | 允许做 | 禁止做 | 输出 |
+| --- | --- | --- | --- |
+| Explorer | 只读调查、找上下文、列风险 | 修改文件、重构、下结论替代验证 | 相关文件、风险点、建议测试 |
+| Test Writer | 只写/改测试和测试 fixtures | 改生产代码、放宽断言 | 失败测试、测试意图 |
+| Implementer | 在指定 write set 内实现 | 触碰未授权文件、扩大 scope | 改动文件、实现说明 |
+| Reviewer | 只读审查边界、过度设计、缺测试 | 修改代码、重排任务 | findings、severity、文件行号 |
+| Verifier | 运行验证命令、汇总结果 | 改业务代码掩盖失败 | 命令、结果、失败原因 |
+
+分工规则：
+- 同一时间并行 subagents 的 write set 必须不重叠。
+- Explorer 和 Reviewer 默认只读。
+- Test Writer 必须先于 Implementer，除非是纯文档或无法自动测试的变更。
+- Implementer 只能执行 feature doc 里列出的 tasks。
+- Verifier 的失败结果必须写回 feature doc，不能只在聊天里口头说明。
+
+---
+
+## 4. TDD 闭环
+
+默认闭环：
+
+```text
+feature doc -> failing test -> minimal implementation -> tests pass -> boundary check -> docs sync -> review -> close
+```
+
+TDD 规则：
+- 新行为先写失败测试，再实现。
+- bug fix 先写复现测试，再修复。
+- 重构先记录现有测试，再移动代码，最后证明行为未变。
+- 无法自动测试时，feature doc 必须写明人工验证步骤和不可自动化原因。
+- 不允许为了通过测试删除关键断言、放宽边界测试或跳过失败测试。
+
+---
+
+## 4.1 矛盾处理
+
+当 agent 发现 PRD、architecture、ports、data-flow、state-machines、tests 或代码互相矛盾时：
+
+1. 停止实现，不继续猜测。
+2. 在 feature doc 的 Decision Log 记录冲突位置、冲突内容、可选解释和推荐选择。
+3. 如果冲突影响安全边界、端口合同、状态机或用户可见行为，先询问维护者。
+4. 如果冲突只影响命名、注释或明显过期文档，可以按代码和测试事实修正 docs，并在 Verification 记录原因。
+5. 修正后再继续 TDD 闭环。
+
+---
+
+## 5. Write Set 和边界
+
+Feature doc 必须写：
+- **Allowed write set**：本次允许修改哪些文件/目录。
+- **Forbidden scope**：明确不碰哪些文件/行为。
+- **Architecture impact**：是否影响 `architecture.md`、`ports.md`、`data-flow.md`、`state-machines.md`。
+- **Rollback note**：失败时如何回退本次改动，不要求回退用户已有改动。
+
+默认禁止：
+- 顺手重构无关模块。
+- 为了实现一个功能修改公共契约但不更新 docs。
+- 让 harness 承担 domain 业务判断。
+- 绕过权限、审计、状态机和边界测试。
+
+---
+
+## 6. 完成标准
+
+一个 feature 只有同时满足这些条件才算完成：
+- Requirements 的验收标准逐条可验证。
+- Tasks 全部完成或明确取消并说明原因。
+- 新增/修改行为有测试或人工验证记录。
+- 测试框架（如 pytest、vitest、go test）通过；如果不能通过，记录具体失败和是否与本次变更相关。
+- 架构边界测试通过，或 feature doc 记录为什么需要改变边界。
+- 受影响 docs 已同步。
+- Reviewer 没有未处理的 critical/high findings。
+
+## 6.1 快车道
+
+满足以下全部条件时，可以不开完整 feature doc，但必须在提交说明或聊天结果里写清验证：
+
+- 只影响拼写、链接、注释、单个测试断言或单行安全修复。
+- 不改变跨层端口、状态机、数据流、权限、审计或用户可见行为。
+- 不新增依赖，不移动文件，不扩大 public API。
+- 能用一个命令或一次人工检查验证。
+
+如果快车道过程中发现影响范围变大，立即补 feature doc。
+
+---
+
+## 7. 外部参考
+
+- OpenAI ExecPlans：复杂任务要有自包含、可恢复、可验证的执行计划。
+- GitHub Spec Kit：constitution -> specify -> plan -> tasks -> implement。
+- Kiro Specs：requirements -> design -> tasks，适合约束 agent 先想清楚再写代码。
+- Claude Code Subagents / Hooks：focused subagents、权限限制、hook-based guardrails。

package/templates/common/docs/harness/architecture.md

@@ -0,0 +1,87 @@
+# Harness Architecture — {{projectName}}
+
+> **职责**：定义系统的分层结构、组件全景和关键设计决策。
+> **不写什么**：代码细节（AI 能读代码）、API 文档（放 docstring）。
+>
+> 哲学来源：arc42 第 5 章 (Building Block View) + C4 Model Level 3 (Component) + matklad 的轻量 ARCHITECTURE.md。
+
+---
+
+## 1. 分层规则
+
+<!-- 这是整个架构最硬性的约束。每个层的"允许依赖什么"必须明确。 -->
+
+```
+┌──────────────────────────┐
+│     interfaces/          │  ← 用户入口（CLI / API / UI）
+│     可依赖: harness       │
+├──────────────────────────┤
+│     harness/             │  ← 通用运行外壳：编排、安全、审计、调度
+│     可依赖: application   │    不包含业务规则
+├──────────────────────────┤
+│     application/         │  ← 业务用例编排
+│     可依赖: domain        │
+├──────────────────────────┤
+│     domain/              │  ← 纯业务对象 + 端口协议
+│     只依赖: 标准库         │    不依赖任何外部实现
+├──────────────────────────┤
+│     infrastructure/      │  ← 适配器实现（数据源、外部服务）
+│     实现 domain 的端口     │
+└──────────────────────────┘
+```
+
+**硬约束**：
+- domain 绝不导入 infrastructure/ 或 interfaces/
+- application 只依赖 domain
+- harness 协调流程但不包含领域业务规则
+- 所有跨层通信通过 domain 定义的端口协议
+
+---
+
+## 2. Harness 核心组件
+
+### 2.1 Runner / Loop
+
+- **职责**：驱动一次任务从输入到完成：加载上下文、调用 application use-case、处理停止条件。
+- **设计决策**：
+  - Runner 只编排，不解释领域含义 — 为什么：保持 harness 可复用于不同业务域
+  - 停止条件显式建模 — 为什么：防止 agent loop 无限运行或静默半完成
+- **不负责**：业务规则、领域对象创建细节、外部服务实现
+
+### 2.2 Permission Policy
+
+- **职责**：决定某个工具、文件、网络或外部动作是否允许执行。
+- **设计决策**：
+  - 默认拒绝高风险动作，允许规则显式声明 — 为什么：底座要先保证安全边界
+- **不负责**：判断业务动作是否正确
+
+### 2.3 Event Bus / Audit Trail
+
+- **职责**：记录任务生命周期、工具调用、失败、人工审批和最终结果。
+- **设计决策**：
+  - 事件追加写入，审计记录不可原地改写 — 为什么：方便回放、排错和复盘
+- **不负责**：替业务系统保存最终数据
+
+### 2.4 State / Checkpoint Store
+
+- **职责**：保存可恢复状态、上下文摘要、任务进度和中断点。
+- **设计决策**：
+  - 状态格式必须可序列化 — 为什么：便于 replay、resume、测试和迁移
+- **不负责**：长期业务数据库建模
+
+### 2.5 Tool Registry
+
+- **职责**：注册可调用工具及其输入/输出契约、权限标签和错误语义。
+- **设计决策**：
+  - 工具契约写清输入、输出、错误和副作用 — 为什么：降低 agent 误用工具的概率
+- **不负责**：工具内部业务实现
+
+---
+
+## 3. 架构约束（不可协商）
+
+- `domain/` 只定义业务模型、业务不变量和端口协议，不导入 `harness/`、`infrastructure/` 或 `interfaces/`。
+- `harness/` 可以协调流程、安全门、审计和停止条件，但不能决定业务含义。
+- 所有跨层外部能力都通过 `domain` 端口表达，适配器实现放在 `infrastructure/`。
+- 拒绝和失败必须能被测试或在 feature doc 中写明人工验证。
+- 审计事件追加记录，不原地改写。

package/templates/common/docs/harness/data-flow.md

@@ -0,0 +1,59 @@
+# 数据流 — {{projectName}}
+
+> **职责**：定义每个事件/请求的完整生命周期——正常路径 + 所有失败分支。
+> **这是整个 docs 里最重要的文件**——AI 实现时最常编造的就是失败路径行为。写清楚就不会。
+>
+> 哲学来源：EventCatalog 模式 + arc42 第 6 章 (Runtime View)。
+
+---
+
+## 1. 事件目录
+
+| 事件类型 | 生产者 | 消费者 | Payload 关键字段 | 投递语义 | 排序要求 |
+| --- | --- | --- | --- | --- | --- |
+| `{{EVENT_1}}` | `{{PRODUCER}}` | `{{CONSUMERS}}` | `{{KEY_FIELDS}}` | {{SEMANTICS}} | {{ORDERING}} |
+
+---
+
+## 2. 核心流程
+
+### 2.1 正常路径
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Runner
+    participant Bus as EventBus/Audit
+    participant Port1 as {{PORT_NAME_1}}
+    participant Port2 as {{PORT_NAME_2}}
+
+    Caller->>Runner: {{ENTRY_POINT}}
+    Runner->>Bus: publish {{START_EVENT}}
+    Runner->>Port1: {{ACTION_1}}
+    Port1-->>Runner: {{RESULT_1}}
+    Runner->>Port2: {{ACTION_2}}
+    Port2-->>Runner: {{RESULT_2}}
+    Runner->>Bus: publish {{END_EVENT}}
+    Runner-->>Caller: {{FINAL_RESULT}}
+```
+
+### 2.2 失败路径
+
+每个失败点必须写清：
+- **触发条件**
+- **系统行为**
+- **事件发布**
+- **调用方感知**
+- **恢复方式**
+
+---
+
+## 3. 错误处理约定
+
+- **可重试错误**：{{POLICY}}
+- **不可重试错误**：{{POLICY}}
+- **静默忽略**：{{POLICY}}
+
+---
+
+> **提示**：当前 data-flow.md 是空模板。请按项目实际流程填写。格式参考 ECC 仓库的实际项目示例。

package/templates/common/docs/harness/state-machines.md

@@ -0,0 +1,50 @@
+# 状态机 — {{projectName}}
+
+> **职责**：定义所有有状态组件的状态、转移、守卫条件、边界行为。长流程 harness 的大量 bug 来自非法状态转移。
+>
+> 哲学来源：UML 2.5.1 第 15.3.14 节 + "转移表是整个文档最重要的产物"。
+
+---
+
+## 状态机模板
+
+每个有状态组件按此格式填写：
+
+### 状态枚举
+
+| 状态 | 描述 | 进入条件 | 退出条件 |
+| --- | --- | --- | --- |
+| `{{STATE_1}}` | {{DESCRIPTION}} | {{CONDITION}} | {{CONDITION}} |
+| `{{STATE_2}}` | {{DESCRIPTION}} | {{CONDITION}} | {{CONDITION}} |
+
+### 状态转移图
+
+```mermaid
+stateDiagram-v2
+    [*] --> {{INITIAL_STATE}}
+    {{INITIAL_STATE}} --> {{STATE_2}} : {{TRIGGER}}
+    {{STATE_2}} --> {{INITIAL_STATE}} : {{TRIGGER}}
+```
+
+### 转移表（最重要）
+
+| 当前状态 ↓ / 事件 → | `{{EVENT_1}}` | `{{EVENT_2}}` | `{{EVENT_3}}` |
+| --- | --- | --- | --- |
+| **`{{STATE_1}}`** | {{TARGET}} | {{TARGET}} | {{TARGET}} |
+| **`{{STATE_2}}`** | {{TARGET}} | {{TARGET}} | {{TARGET}} |
+
+### 守卫条件
+
+| 转移 | 守卫条件 | 备注 |
+| --- | --- | --- |
+| `{{SOURCE}} -> {{TARGET}}` | {{GUARD}} | {{NOTE}} |
+
+### 非法转移
+
+| 转移 | 为什么非法 |
+| --- | --- |
+| `{{SOURCE}} -> {{TARGET}}` | {{REASON}} |
+
+---
+
+> **提示**：当前 state-machines.md 是空模板。请按项目实际的有状态组件填写。