@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/design/frontend-architecture.md

@@ -0,0 +1,147 @@
+# Frontend Architecture 模板
+
+> 目标: 在前端实现前声明页面、feature、组件、状态、API、样式和测试边界，防止把整页逻辑堆到一个组件里。
+
+## 1. 基本信息
+
+- Feature ID:
+- 页面 / 模块:
+- 关联需求:
+- 关联路由:
+- 目标质量等级: P0 / P1 / P2 / P3
+- 设计真相源:
+- Contract 真相源:
+- 最后更新:
+
+## 2. 架构目标
+
+- 本次前端架构要解决的问题:
+- 需要支持的用户流程:
+- 本期不处理的能力:
+- 主要风险:
+
+## 3. 分层与目录
+
+| 层级 | 建议路径 | 职责 | 禁止事项 |
+| --- | --- | --- | --- |
+| Page / Route | `app/...` / `pages/...` | 路由、布局组合、数据预取入口 | 写业务细节和 UI primitive |
+| Feature | `features/<domain>/` | 业务组件、业务 hooks、权限、字段映射 | 放跨业务通用组件 |
+| UI primitives | `packages/ui/` / `components/ui/` | 无业务语义的基础组件 | 依赖 API、权限或业务枚举 |
+| Data table / List | `packages/ui/data-table/` 或 feature 内 | 排序、筛选、分页、列显隐 | 混入具体业务字段文案 |
+| API client | `packages/api-client/` / `features/<domain>/api/` | HTTP 调用、契约生成 client | 直接操作 UI 状态 |
+| Model / Schema | `features/<domain>/model/` | 类型、枚举、校验、URL query 解析 | 把展示样式写进 schema |
+
+## 4. 组件树
+
+```text
+<Page>
+  <FeatureShell>
+    <Toolbar />
+    <FilterBar />
+    <Content />
+    <Pagination />
+    <DialogOrDrawer />
+  </FeatureShell>
+</Page>
+```
+
+| 组件 | 层级 | 职责 | 数据输入 | 事件输出 | 可复用范围 |
+| --- | --- | --- | --- | --- | --- |
+| | Page / Feature / Primitive | | | | local / feature / project |
+
+## 5. 状态管理
+
+| 状态 | 所属层级 | 来源 | 持久化方式 | 变化事件 | 测试方式 |
+| --- | --- | --- | --- | --- | --- |
+| URL filters | Page / Feature | query string | URL | filter change / reset | e2e |
+| Remote data | Feature | API client | cache / none | fetch / refetch | mock + e2e |
+| Form state | Component | user input | local | submit / cancel | interaction |
+| UI state | Component | user interaction | local | open / close | story |
+
+规则:
+
+- 可分享、可回退、影响查询结果的状态优先进入 URL。
+- 远程数据状态不得散落在多个展示组件中。
+- 表单 dirty、提交中、提交失败必须有明确状态来源。
+- 权限状态必须能追溯到 PRD、auth context 或 contract。
+
+## 6. API 与数据边界
+
+| UI 需求 | API / Contract | 字段 | 错误态 | 前端兜底 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+规则:
+
+- UI 字段必须能追溯到 contract 或 PRD 数据字典。
+- 展示组件不得拼接 HTTP URL 或处理响应状态码。
+- API client 抛出的错误必须映射到用户可理解的错误态。
+- mock 数据必须覆盖 default / empty / error / long_content / permission。
+
+## 7. 响应式架构
+
+| 视口 | 结构 | 筛选策略 | 列表 / 表格策略 | 操作区策略 | 必需截图 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop >= 1200px | | | | | |
+| Tablet 768-1199px | | | | | |
+| Mobile < 768px | | | | | |
+
+规则:
+
+- 移动端主要流程不能只依赖横向滚动。
+- 表格转卡片时必须说明字段优先级。
+- 操作区折叠时必须保留主操作可见或一跳可达。
+
+## 8. 动效与可访问性
+
+| 组件 / 场景 | 动效 | reduced motion 行为 | 焦点 / 键盘规则 | ARIA / 语义 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+规则:
+
+- 动效只用于状态解释，不用于隐藏加载或错误。
+- 弹窗、抽屉、菜单必须定义焦点进入、循环、关闭和恢复。
+- 状态变化、错误和保存结果必须有屏幕阅读器可感知的反馈。
+
+## 9. 性能预算
+
+| 风险 | 阈值 / 预算 | 处理策略 | 验证方式 |
+| --- | --- | --- | --- |
+| 列表行数 | | client / server / virtualized | |
+| 首屏依赖 | | lazy / split / avoid | |
+| 图片 / 图标 | | optimize / sprite / lazy | |
+| 动效 | | transform / opacity | |
+
+## 10. Story 与测试矩阵
+
+| 状态 / 场景 | Story | Interaction | E2E | Visual | A11y | Performance |
+| --- | --- | --- | --- | --- | --- | --- |
+| default | | | | | | |
+| loading | | | | | | |
+| empty | | | | | | |
+| error | | | | | | |
+| permission | | | | | | |
+| long_content | | | | | | |
+| mobile | | | | | | |
+
+## 11. 复用决策
+
+| 候选组件 / Hook | 复用范围 | 是否抽象 | 原因 | 约束 |
+| --- | --- | --- | --- | --- |
+| | local / feature / project | Yes / No | | |
+
+抽象规则:
+
+- 基础 primitive 可以直接进入通用层。
+- 业务组件默认留在 feature 内。
+- 只有当第二个真实使用场景出现或 DEV-PLAN 明确要求时，才抽项目级复用组件。
+
+## 12. 完成标准
+
+- [ ] 组件分层与目录边界已明确。
+- [ ] 状态来源、持久化和事件已明确。
+- [ ] API 字段和错误态已追溯到 contract 或 PRD。
+- [ ] 响应式结构有 desktop / tablet / mobile 策略。
+- [ ] 动效、reduced motion、键盘和可访问性规则已定义。
+- [ ] Story / E2E / visual / a11y / performance 证据路径已定义。

package/package-source/docs/codex-harness-engineering/templates/design/image-to-frontend-spec.md

@@ -0,0 +1,108 @@
+# Image To Frontend Spec 模板
+
+> 目标: 把评审通过的 UI 图片转换成可实现的前端规格。前端编码只能依据本规格、Design Tokens、Component Map 和 Screen States，不直接凭图片猜实现。
+
+## 1. 输入图片
+
+| Image ID | Page ID | State | 图片路径 / 链接 | 评审结论 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | page-001 | default | | PASS |
+
+## 2. 页面布局规格
+
+| 区域 | 位置 | 尺寸 / 约束 | 内容 | 响应式行为 |
+| --- | --- | --- | --- | --- |
+| Header | | | | |
+| Main | | | | |
+| Aside | | | | |
+| Footer / Action Bar | | | | |
+
+## 3. 组件实现映射
+
+| 图片元素 | 前端组件 | 层级 | 复用来源 | Props / 数据 | 事件 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| | | page / feature / primitive | existing / new | | | default |
+
+## 4. CSS / Token 映射
+
+| 图片表现 | Token / CSS 变量 | 值 | 备注 |
+| --- | --- | --- | --- |
+| 主背景 | `--color-bg-default` | | |
+| 主文字 | `--color-text-primary` | | |
+| 间距 | `--space-*` | | |
+| 圆角 | `--radius-*` | | |
+
+## 5. 状态实现规格
+
+| State | 数据条件 | UI 行为 | 组件变化 | 动效 | 测试 |
+| --- | --- | --- | --- | --- | --- |
+| default | | | | | story / e2e / visual |
+| empty | | | | | story / e2e / visual |
+| loading | | | | | story / visual |
+| error | | | | | story / e2e / visual |
+
+## 5.1 响应式实现规格
+
+| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop 1440x900 | | | | | required |
+| Tablet 768x1024 | | | | | required / optional |
+| Mobile 375x812 | | | | | required |
+
+## 5.2 动效与可访问性规格
+
+| 场景 | 动效 | reduced motion | 键盘 / 焦点 | ARIA / 状态提示 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+## 6. Mock 数据
+
+| 场景 | 数据文件 / 生成方式 | 覆盖状态 |
+| --- | --- | --- |
+| default | | |
+| empty | | |
+| error | | |
+| long_content | | |
+
+## 7. 实现任务输入
+
+- 必读:
+  - `docs/product/requirement-interface-matrix.md`
+  - `docs/harness/frontend-quality-rules.md`
+  - `docs/design/frontend-architecture.md`
+  - `docs/design/component-map.md`
+  - `docs/design/screen-states.md`
+  - `docs/design/design-tokens.json`
+  - 本文件
+- 必须输出:
+  - 前端组件 / 页面
+  - stories
+  - mock 数据
+  - visual baseline 或截图证据
+  - a11y smoke 和 responsive 截图证据
+
+## 8. 视觉还原验证计划
+
+| Page ID | State | Viewport | Route / URL | 数据准备 | 参考图 | 实拍截图 | 对比报告 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| page-001 | default | Desktop 1440x900 | | | `docs/design/assets/.../reference.png` | `artifacts/visual-review/.../actual.png` | `artifacts/visual-review/.../review.md` |
+
+规则:
+
+- 前端实现完成后，必须启动真实浏览器访问页面并截图。
+- 截图必须保存到 `artifacts/visual-review/<feature>/<page>/`。
+- 参考图必须来自已通过 `ui-image-review.md` 的设计图。
+- 对比过程使用 `visual-parity-review.md`，结论为 `PASS` 才能通过 Stage 1。
+- 如果 UI 和设计图不一致，必须修复前端代码并重新截图，不允许只改验收文档绕过。
+
+## 9. 通过标准
+
+- [ ] 图片中的每个可见业务元素都有组件映射。
+- [ ] 每个组件都能追溯到数据、事件和状态。
+- [ ] 每个组件都声明了 page / feature / primitive 层级和复用边界。
+- [ ] CSS 实现可以从 token 或明确规则得出。
+- [ ] 响应式行为可以从 viewport 规格得出。
+- [ ] 动效和 reduced motion 行为已明确。
+- [ ] 没有直接从图片猜出的隐藏业务逻辑。
+- [ ] 前端实现任务不再需要重新做视觉决策。
+- [ ] 真实浏览器截图与设计参考图完成视觉还原对比，`visual-parity-review.md` 结论为 PASS。

package/package-source/docs/codex-harness-engineering/templates/design/screen-states.md

@@ -0,0 +1,122 @@
+# Screen States 模板
+
+> 目标: 把每个页面状态写成可实现、可做 story、可做 visual regression 的状态规格。
+
+## 页面名称
+
+- Page ID:
+- 页面:
+- 路由/入口:
+- 角色:
+- 关联需求:
+- 关联设计稿:
+
+## 状态清单
+
+### default
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+### empty
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复路径:
+- story 名称:
+- visual baseline:
+
+### loading
+
+- 触发条件:
+- 等待对象:
+- 页面表现:
+- 用户可执行动作:
+- 超时后行为:
+- story 名称:
+- visual baseline:
+
+### error
+
+- 触发条件:
+- 错误类型:
+- 页面表现:
+- 用户可执行动作:
+- 重试 / 兜底:
+- story 名称:
+- visual baseline:
+
+### permission_denied
+
+- 触发条件:
+- 权限规则:
+- 页面表现:
+- 用户可执行动作:
+- 是否隐藏受限操作:
+- story 名称:
+- visual baseline:
+
+### disabled
+
+- 触发条件:
+- 禁用对象:
+- 禁用原因展示:
+- 用户可执行动作:
+- 恢复条件:
+- story 名称:
+- visual baseline:
+
+### long_content
+
+- 触发条件:
+- 极端数据:
+- 页面表现:
+- 用户可执行动作:
+- 截断 / 换行 / tooltip 规则:
+- story 名称:
+- visual baseline:
+
+### responsive/mobile
+
+- 触发条件:
+- 断点:
+- 页面表现:
+- 用户可执行动作:
+- 折叠策略:
+- 表格 / 列表替代形态:
+- 主操作可达性:
+- 触控目标:
+- 长文本 / 长标签处理:
+- story 名称:
+- visual baseline:
+
+### motion/reduced_motion
+
+- 触发条件:
+- 默认动效:
+- reduced motion 表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+## 状态到测试映射
+
+| 状态 | Story | Interaction Test | E2E | Visual |
+| --- | --- | --- | --- | --- |
+| default | | | | |
+| empty | | | | |
+| loading | | | | |
+| error | | | | |
+| permission_denied | | | | |
+| disabled | | | | |
+| long_content | | | | |
+| mobile | | | | |
+| reduced_motion | | | | |

package/package-source/docs/codex-harness-engineering/templates/design/ui-image-review.md

@@ -0,0 +1,60 @@
+# UI Image Review 模板
+
+> 目标: 对 AI 生成的前端界面图进行评审。图片未通过前，不进入前端规范和代码实现。
+
+## 1. 评审对象
+
+| Image ID | Page ID | State | 图片路径 / 链接 | 版本 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | page-001 | default | | v1 |
+
+## 2. 需求匹配检查
+
+| Requirement ID | 图片是否体现 | 证据 | 问题 | 结论 |
+| --- | --- | --- | --- | --- |
+| FR-001 | Yes / No / Partial | | | Pass / Fail |
+
+## 3. 状态覆盖检查
+
+| Page ID | State | 是否有图 | 是否符合 Screen States | 问题 | 结论 |
+| --- | --- | --- | --- | --- | --- |
+| page-001 | default | Yes | Yes / No | | Pass / Fail |
+
+## 4. 视觉与 CSS 规范检查
+
+| 检查项 | 预期 | 图片表现 | 结论 |
+| --- | --- | --- | --- |
+| 颜色 | | | Pass / Fail |
+| 字体 / 字号 | | | Pass / Fail |
+| 间距 | | | Pass / Fail |
+| 圆角 / 阴影 | | | Pass / Fail |
+| 信息密度 | | | Pass / Fail |
+| 响应式 | | | Pass / Fail |
+
+## 5. 交互与边界检查
+
+| 检查项 | 是否满足 | 问题 | 处理 |
+| --- | --- | --- | --- |
+| 主操作清晰 | Yes / No | | |
+| 空态可恢复 | Yes / No / N/A | | |
+| 错误态可重试 | Yes / No / N/A | | |
+| 权限差异清晰 | Yes / No / N/A | | |
+| 长文本不破版 | Yes / No / N/A | | |
+| 没有多余功能 | Yes / No | | |
+
+## 6. 评审结论
+
+- Verdict: PASS / FAIL
+- 必须重生成的图片:
+- 可通过编辑修复的图片:
+- 通过后进入: `image-to-frontend-spec.md`
+- 前端实现后还必须进入: `visual-parity-review.md`
+
+## 7. 通过标准
+
+- [ ] 每个 required state 都有图片或明确豁免。
+- [ ] 每个 P0/P1 需求都能在至少一张图中找到界面证据。
+- [ ] 图片没有添加需求之外的功能。
+- [ ] 图片符合 CSS / token / 组件规范。
+- [ ] 评审问题已关闭或转为新的图片编辑提示词。
+- [ ] 图片已作为后续浏览器截图对比的 reference source 记录保存路径。

package/package-source/docs/codex-harness-engineering/templates/design/visual-parity-review.md

@@ -0,0 +1,124 @@
+# Visual Parity Review 模板
+
+> 目标: 前端实现完成后，必须在真实浏览器中截图，并把实拍图与已评审通过的 UI 设计图对比。没有浏览器截图和图片对比证据，前端 UI 任务不能通过 Stage 1 Review。
+
+## 1. 评审对象
+
+| Feature ID | Page ID | State | Viewport | Route / URL | 设计参考图 | 浏览器实拍图 | 对比结论 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| | | default | Desktop 1440x900 | | `docs/design/assets/<feature>/<page>/default-desktop-reference.png` | `artifacts/visual-review/<feature>/<page>/default-desktop-actual.png` | PASS / FAIL |
+
+## 2. 前置条件
+
+- `ui-image-review.md` 对应图片已 PASS。
+- `image-to-frontend-spec.md` 已把设计图转成布局、组件、CSS/token、状态和数据规格。
+- 页面可以在真实浏览器打开。
+- 测试数据固定，避免商品名、价格、图片数量等动态内容导致误判。
+- 截图前关闭调试浮层、cookie 弹窗、浏览器扩展遮挡和非业务 toast。
+
+## 3. 产物目录规范
+
+```text
+docs/design/assets/<feature>/<page>/
+  <state>-<viewport>-reference.png
+
+artifacts/visual-review/<feature>/<page>/
+  <state>-<viewport>-actual.png
+  <state>-<viewport>-diff.png
+  <state>-<viewport>-review.md
+```
+
+说明:
+
+- `reference.png` 是评审通过的设计图或从设计稿导出的基准图。
+- `actual.png` 必须来自真实浏览器截图，不允许用设计图、静态 mock 图或裁剪后的局部图替代。
+- `diff.png` 可由视觉回归工具生成；如果没有像素 diff 工具，也必须生成 `review.md` 记录视觉模型或人工评审结论。
+- `artifacts/visual-review/` 可以进入 Git，也可以作为 CI artifact；如果不入 Git，trace / handoff 必须记录路径。
+
+## 4. 截图矩阵
+
+| Page ID | State | Viewport | 数据准备 | 参考图 | 实拍图 | 必须评审 |
+| --- | --- | --- | --- | --- | --- | --- |
+| | default | Desktop 1440x900 | | | | Yes |
+| | empty | Desktop 1440x900 | | | | Yes / N/A |
+| | loading | Desktop 1440x900 | | | | Yes / N/A |
+| | error | Desktop 1440x900 | | | | Yes / N/A |
+| | permission | Desktop 1440x900 | | | | Yes / N/A |
+| | long_content | Desktop 1440x900 | | | | Yes / N/A |
+| | default | Tablet 768x1024 | | | | Yes / N/A |
+| | default | Mobile 375x812 | | | | Yes / N/A |
+| | reduced_motion | Desktop 1440x900 | | | | Yes / N/A |
+
+## 5. 浏览器截图命令示例
+
+Playwright CLI 示例:
+
+```powershell
+New-Item -ItemType Directory -Force -Path .\artifacts\visual-review\pet-mall\home | Out-Null
+$env:VISUAL_BASE_URL = "http://localhost:5173"
+npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" ".\artifacts\visual-review\pet-mall\home\default-desktop-actual.png"
+```
+
+如果项目使用 browser / devtools 工具执行 E2E，也必须把截图保存到 `artifacts/visual-review/...`，并在报告中写明截图路径。
+
+## 6. 图片对比 Prompt
+
+把设计参考图和浏览器实拍图同时交给具备图片理解能力的 reviewer，使用以下提示词:
+
+```text
+请对比这两张图：
+1. 第一张是已评审通过的 UI 设计参考图。
+2. 第二张是真实浏览器截图。
+
+请只评审视觉还原，不重新设计页面。
+
+必须检查：
+- 页面结构、主次区域、导航、卡片、列表、表单和操作区是否一致。
+- 字体、字号、字重、行高、间距、圆角、阴影、边框、颜色是否明显偏离。
+- 商品图、图标、按钮、标签、价格、状态文本等业务元素是否缺失或多出。
+- 空态、加载态、错误态、移动端状态是否符合设计图和 screen-states。
+- 是否有文字溢出、遮挡、错位、重叠、响应式破版。
+- 动效、reduced motion、focus、hover、disabled 是否符合规格或有截图 / 录像证据。
+- 移动端触控目标、折叠策略、表格替代形态是否符合 screen-states 和 frontend architecture。
+
+输出：
+- Verdict: PASS / FAIL
+- 主要差异清单
+- 必须修复项
+- 可接受差异及原因
+```
+
+## 7. 对比记录
+
+| 检查项 | 参考图表现 | 实拍图表现 | 结论 | 修复任务 |
+| --- | --- | --- | --- | --- |
+| 布局结构 | | | PASS / FAIL | |
+| 字体与字号 | | | PASS / FAIL | |
+| 间距与密度 | | | PASS / FAIL | |
+| 颜色与状态色 | | | PASS / FAIL | |
+| 组件圆角 / 阴影 / 边框 | | | PASS / FAIL | |
+| 业务元素完整性 | | | PASS / FAIL | |
+| 响应式 | | | PASS / FAIL / N/A | |
+| 动效 / reduced motion | | | PASS / FAIL / N/A | |
+| 可访问性可见状态 | | | PASS / FAIL / N/A | |
+
+## 8. 失败处理
+
+如果 Verdict 为 FAIL:
+
+1. 把差异写入当前 task 的 `progress.txt` 或 worker `handoff.md`。
+2. 生成前端修复任务，明确允许修改的文件和必须重跑的截图矩阵。
+3. 修复后重新启动页面，重新截图。
+4. 用新的 `actual.png` 再次对比，直到 Verdict 为 PASS。
+5. 如果连续多轮仍无法一致，输出 `BLOCKED`，说明是设计图、规格、数据或技术约束冲突。
+
+## 9. 通过标准
+
+- [ ] 每个 required UI state 都有参考图或明确豁免。
+- [ ] 每个 required UI state 都有真实浏览器截图。
+- [ ] mobile required viewport 有真实浏览器截图或明确豁免。
+- [ ] 可访问性、focus、reduced motion 的可见状态已有截图、录像或报告证据。
+- [ ] 截图 viewport、测试数据和页面状态与参考图一致。
+- [ ] 图片对比报告存在，并给出 `Verdict: PASS`。
+- [ ] 所有 FAIL 差异都已修复并重新截图。
+- [ ] Stage 1 Review 能读取参考图路径、实拍图路径和对比报告。

package/package-source/docs/codex-harness-engineering/templates/docs/architecture-constraints.md

@@ -0,0 +1,83 @@
+# Architecture Constraints Packet
+
+本文件在需求分析结束、进入计划或编码前完成。它把“系统应该是什么形态”转成可执行约束，供 `task.json`、Stage 1 Review 和验证命令使用。
+
+默认路径是 `docs/architecture/constraints.md`。项目可以在 `task.json.runtime.handoff.truth_sources.architecture` 中改用其他路径，但后续任务、prompt 和 review 必须读取同一组 truth source。
+
+## 1. System Shape
+
+- `delivery_shape`: `web_app` / `backend_service` / `monolith` / `frontend_app` / `cli` / `library` / `automation` / `data_pipeline` / `domain_prototype` / `other:<name>`
+- `runtime_model`: `http_service` / `worker` / `scheduled_job` / `static_site` / `embedded_library` / `command` / `not_applicable`
+- `deployment_unit`: `container` / `single_process` / `serverless` / `package` / `static_assets` / `not_applicable`
+- `production_entrypoints`: 列出当前项目真实启动入口、公开命令、页面入口、worker entry、package export、Dockerfile 或 `not_applicable`。
+
+## 2. Public Interface Boundary
+
+- `public_interfaces`: `HTTP` / `gRPC` / `GraphQL` / `MQ` / `CLI` / `UI route` / `package API` / `file format` / `none`
+- `contract_source`: `OpenAPI` / `protobuf` / `GraphQL schema` / `existing API` / `typed API` / `docs` / `not_applicable`
+- `interface_trace_rule`: 每个公开入口应能追踪到实现、测试和证据路径；没有公开入口时写明 `not_applicable`。
+
+## 2.1 Service And Contract Topology
+
+多服务、多仓库、契约或外部系统项目必须声明服务拓扑；不适用时写明 `service_matrix: not_applicable`。
+
+- `service_matrix`: `.service-matrix/dependencies.yaml` / `not_applicable` / `project_defined:<path>`
+- `affected_services`: 本轮需求会修改或影响的服务、应用、包、worker、前端入口或外部系统。
+- `upstream_downstream_rule`: 说明上游调用方和下游依赖方如何确认；不能只依赖代码搜索。
+- `contract_branch_rule`: IDL、OpenAPI、schema、generated code 或外部契约是否需要同分支、同版本或兼容性证明。
+- `change_gate_rule`: 对应 contract diff、consumer test、integration test、mock 更新、灰度或回滚检查。
+
+## 3. Data Boundary
+
+- `persistence_boundary`: `MySQL` / `PostgreSQL` / `SQLite` / `Redis` / `object_storage` / `filesystem` / `browser_storage` / `external API` / `none`
+- `schema_or_migration_required`: `yes` / `no` / `not_applicable`
+- `repository_policy`: 说明声明交付路径使用的真实数据边界；测试替身、fixture、mock adapter 或 local-only adapter 只能用于声明允许的范围。
+- `consistency_requirements`: 事务、锁、幂等键、唯一约束、审计保留、缓存失效、离线同步或 `not_applicable`。
+
+## 4. Async And Worker Boundary
+
+- `async_required`: `yes` / `no`
+- `scheduling_model`: `DB polling` / `MQ consumer` / `cron` / `event bus` / `browser event` / `manual command` / `none`
+- `concurrency_control`: `DB row lock` / `optimistic CAS` / `distributed lock` / `single process` / `browser single-thread` / `none`
+- `time_source`: `database time` / `server time` / `event time` / `browser time` / `not_applicable`
+
+## 5. Test Double Policy
+
+- `test_double_allowed_scope`: `unit_tests_only` / `contract_tests` / `local_demo` / `domain_prototype` / `not_allowed` / `project_defined:<rule>`
+- `mock_as_acceptance_evidence`: `no` by default；如果允许，必须写明原因、适用依赖、过期条件和替代真实验证计划。
+- `minimum_integration_evidence`: 列出当前项目最低真实验证组合，例如 UI + API、API + DB、CLI + filesystem、package API + consumer test、worker + queue，或 `not_applicable`。
+
+## 6. Forbidden Implementations
+
+按项目填充，不要只写抽象原则。示例只作为选项，不代表所有项目都适用：
+
+- 不允许只实现领域 service 而没有任务声明的公开入口。
+- 不允许公开契约有 operation 但代码没有对应实现或验证。
+- 不允许用测试替身、mock、fixture、local-only adapter 冒充声明交付路径。
+- 不允许把 `domain_prototype` 标记为可交付功能完成。
+- 不允许只运行 `git diff --check` 就声明 `feature_impl` 完成。
+
+## 7. Architecture Fitness Checks
+
+每个项目至少定义一个可运行或可审查的架构适配检查，并把命令或检查项同步到 `task.json` 的 `test_command`。
+
+```powershell
+<replace-with-project-fitness-check>
+```
+
+若暂时没有脚本，必须在 `docs/testing/verify-matrix.md` 写明等价检查项。可选检查包括：
+
+- 声明的生产入口存在，且能被启动、导入、访问或执行。
+- 公开接口与实现、测试和证据路径可追踪。
+- 声明交付路径未引用禁止的测试替身。
+- 需要持久化、worker、浏览器、文件或第三方服务时，存在对应的真实验证证据。
+- 不适用的边界已明确标记为 `not_applicable`，而不是留空。
+
+## 8. Definition Of Done
+
+- `architecture_constraints` 已从本文件或等价 truth source 复制到每个相关 `feature_impl` 任务。
+- 多服务、多仓库或契约任务已把服务矩阵、受影响服务和 change gates 复制到相关 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `forbidden_implementations` 已覆盖当前项目最容易跑偏的替代实现。
+- `test_command` 包含项目适配检查、affected tests、必要契约/集成/端到端验证和 `git diff --check`。
+- Stage 1 Review 对声明的架构形态给出 PASS。
+- 完成声明能说明声明交付路径、测试替身和不适用边界。