@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,147 +0,0 @@
-# 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

@@ -1,108 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-# 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

@@ -1,124 +0,0 @@
-# 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

@@ -1,83 +0,0 @@
-# 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。
-- 完成声明能说明声明交付路径、测试替身和不适用边界。