@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/frontend-quality-rules.md

@@ -0,0 +1,138 @@
+# Frontend Quality Rules
+
+本文件定义前端页面从“能用”到“可交付”的最低质量尺子。它服务于 `spec-to-ui-to-code-workflow.md`、`design-brief.md`、`image-to-frontend-spec.md`、`component-map.md`、`screen-states.md` 和 `visual-parity-review.md`，不替代项目自己的品牌规范或产品需求。
+
+## 1. 质量分级
+
+| 等级 | 定义 | 必备证据 | 不能声称 |
+| --- | --- | --- | --- |
+| P0 可用 | 主路径能完成，关键控件可操作 | 主路径 story 或 E2E，基本截图 | 生产级体验 |
+| P1 完整 | default / loading / empty / error / permission / long content / mobile 有规格和验证 | 状态矩阵、story 覆盖、移动端截图 | 视觉精修完成 |
+| P2 精修 | 视觉层级、响应式、动效、可访问性和文案有明确标准并通过评审 | visual parity、a11y smoke、responsive matrix | 可无限复用 |
+| P3 生产级 | 架构可维护，组件边界清晰，性能预算和回归证据完整 | frontend architecture、performance budget、regression evidence | 无需后续治理 |
+
+`feature_impl` 的前端任务如果没有写明目标等级，默认按 P1 验收；用户可见核心流程默认至少 P2。
+
+## 2. 审美反模式
+
+以下情况出现任意一项，Stage 1 或视觉评审应要求返工，除非 Design Brief 明确说明原因：
+
+- 页面只由大块卡片堆叠组成，缺少信息层级。
+- 全页面灰白无重点，主要操作、危险操作和状态反馈不可区分。
+- 使用无意义渐变、装饰图形或营销式 hero 来包装操作型后台页面。
+- 所有按钮、标签、状态、表格行的视觉权重相同。
+- 表格密度失控：行高、列宽、数字、标签和操作区没有扫描节奏。
+- 移动端只做横向滚动，没有重排、折叠或卡片化策略。
+- loading / empty / error 只是一行临时文案，没有恢复路径。
+- 图标、颜色或动画只起装饰作用，不能帮助识别状态或操作。
+
+## 3. 动效规则
+
+动效必须解释状态变化，不承担主要信息表达。
+
+| 场景 | 推荐动效 | 时长 | 约束 |
+| --- | --- | --- | --- |
+| 弹窗 / 抽屉打开 | opacity + scale 或 translate | 120-180ms | 必须有焦点管理 |
+| 筛选 chip 增删 | opacity + slight translate | 100-160ms | 不得推动整页大范围跳动 |
+| 表格刷新 | skeleton / row fade | 120-220ms | 高频刷新时禁用行级动画 |
+| 空态 / 错误态切换 | opacity | 120-180ms | 文案和恢复操作优先 |
+| 保存成功 / dirty 清除 | button state + inline status | 120-180ms | 不得只依赖 toast |
+
+硬约束：
+
+- 首选 `transform` 和 `opacity`，不得用会持续触发布局的动画属性。
+- 必须支持 `prefers-reduced-motion` 或等价 reduced motion 开关。
+- 动效不能隐藏错误、禁用、权限不足或保存失败。
+- 动效失败时页面仍必须可用。
+
+## 4. 响应式规则
+
+每个用户可见页面都必须写清楚 desktop / tablet / mobile 的布局策略。
+
+| 视口 | 必须说明 | 常见策略 |
+| --- | --- | --- |
+| Desktop >= 1200px | 主内容宽度、侧栏、表格列、操作区位置 | 横向筛选条 + 数据表 + 分页 |
+| Tablet 768-1199px | 筛选换行、列显隐、操作折叠 | 筛选条换行，次要列隐藏 |
+| Mobile < 768px | 筛选入口、表格替代形态、底部操作、触控尺寸 | 筛选抽屉，表格转卡片，分页简化 |
+
+移动端禁止只依赖横向滚动完成主要流程。若表格必须横向滚动，必须说明原因、最小宽度、冻结列或摘要卡片替代方案。
+
+## 5. 组件复用边界
+
+- `ui primitives`: 只放按钮、输入、弹窗、菜单、表格基础结构等无业务语义组件。
+- `data-table`: 只放排序、筛选、分页、列显隐、空态容器等表格通用行为。
+- `features/<domain>`: 放业务组件、业务 hooks、字段映射、权限逻辑和页面组合。
+- `api-client`: 放契约生成或手写 API 调用，不直接依赖 UI。
+- `model/schema`: 放类型、枚举、表单校验和 URL query 解析。
+
+复用准入：
+
+- 新通用组件必须至少有两个明确使用场景，或是基础 primitive。
+- 业务语义不稳定时留在 feature 内，不提前抽到 `packages/ui`。
+- 通用组件必须有 props 契约、状态矩阵、story 和可访问性说明。
+- generated types 可以作为数据输入类型，不能决定 UI primitive 的命名和职责。
+
+## 6. 交互与文案规则
+
+每个关键操作必须定义：
+
+- 触发条件、禁用条件、加载反馈、成功反馈、失败反馈。
+- inline error、toast、modal confirm 的使用边界。
+- dirty 状态如何产生、如何保存、何时清除。
+- 重试、取消、关闭、返回是否保留用户输入。
+- 空态文案、错误文案、权限文案、按钮文案和长文本截断规则。
+
+空态必须区分“系统没有数据”和“筛选后没有结果”。错误态必须包含用户可执行的恢复路径。
+
+状态不是给评审看的页面说明。`loading / empty / error / disabled / permission / mobile` 等状态必须由真实状态源驱动，例如 API 请求状态、权限结果、空数据集合、表单 dirty/valid 状态、路由或 query 参数、feature flag、响应式断点、story controls 或可控 mock。页面可以有用户可见文案，但不能出现“这里是 loading 状态”“权限态展示如下”等占位说明来冒充实现。
+
+每个 P0/P1 状态都必须能在代码和证据中追溯到：
+
+- 状态源：store、query、hook、props、fixture、mock response、viewport 或权限判断。
+- 渲染分支：组件条件分支、状态组件、disabled 属性、error boundary、empty renderer 或 responsive layout。
+- 触发路径：用户操作、API 响应、测试 seed、story control、query 参数、mock scenario 或 viewport。
+- 复验证据：story、interaction test、E2E 步骤、截图矩阵或 visual parity finding。
+
+## 7. 可访问性规则
+
+前端规格至少覆盖：
+
+- 键盘路径和焦点顺序。
+- 弹窗、抽屉、菜单的 focus trap 和关闭方式。
+- 表单错误与输入控件的关联。
+- 加载、保存成功、失败的屏幕阅读器提示。
+- 色彩不能作为唯一信息来源。
+- 移动端触控目标不小于 44x44px，除非平台规范另有说明。
+
+## 8. 性能预算
+
+前端设计阶段必须说明是否存在以下风险：
+
+- 首屏依赖过多组件、图标、图表或动画库。
+- 表格超过 100 行、复杂筛选、虚拟滚动或服务端分页需求。
+- 图片、头像、缩略图或远程媒体影响布局稳定。
+- 动效或重排可能影响滚动和输入响应。
+
+如果页面包含复杂表格、图表或列表，必须在 `frontend-architecture.md` 或 DEV-PLAN 中写明 client/server 分界和性能验证方式。
+
+## 9. 证据要求
+
+前端任务完成声明至少包含：
+
+- story / interaction / E2E 中的对应状态覆盖。
+- desktop 和 mobile 的真实浏览器截图。
+- visual parity 结论。
+- 可访问性 smoke 结论或明确豁免。
+- 性能风险检查结论；复杂页面需附性能预算验证。
+
+## 10. State Surface Gate
+
+前端任务进入实现前，必须把状态暴露方式写进 plan 或当前 task 的 `state_surface`。可接受的状态表面包括：
+
+- Storybook / story 文件：适合组件、页面片段、状态矩阵和视觉回归。
+- 真实 route + query / fixture：适合页面级状态、权限态和深链路复现。
+- Mock scenario / MSW / API fixture：适合 loading、empty、error、权限和异常返回。
+- E2E seed / test data：适合跨页面流程、保存、删除、批量操作和副作用验证。
+- Viewport matrix：适合响应式、移动端重排和触控行为。
+
+每个 P0/P1 状态至少要有一个可运行入口，并写明评审看哪里、回归跑什么、失败证据放哪里。状态只存在于设计稿、截图或聊天说明中时，Stage 1 应要求补状态表面，而不是让实现任务继续猜。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/governance-auto-repair.md

@@ -0,0 +1,80 @@
+# Governance Auto Repair
+
+本文件记录 Stop hook 治理检查在会话结束时发现的 Harness 漂移、失败 trace 和可复用修复经验。它是自动化经验暂存区，不是硬规则入口。
+
+## 写入来源
+
+Stop hook 会调用：
+
+```powershell
+scripts/harness/harness-governance-check.ps1 -WriteExperience
+```
+
+该脚本只做两类写入：
+
+- 为新的 failed trace 追加一条去重后的 `Stop Hook Experience`。
+- 创建本文件的基础结构。
+
+它不会直接改 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或 task queue。
+
+## 经验提升规则
+
+每条自动记录的经验都必须经过复验后再提升：
+
+| 情况 | 提升目标 |
+| --- | --- |
+| 重复出现的规则分层、fallback、autoload、hook 漂移 | `docs/harness/rule-governance.md` 或 `.codex/rules/*.md` |
+| 命令权限、危险操作、sandbox 误用 | `.codex/rules/*.rules` 或 `docs/harness/sandbox-policy.md` |
+| Stage 1 产品/设计/计划不一致 | 对应 product/design/plan truth source |
+| Stage 2 代码质量、测试缺口、回归风险 | `docs/testing/failure-triage.md` 或测试矩阵 |
+| driver、trace、progress、commit gate 闭环缺口 | `docs/harness/task-session-strategy.md` 或 `trace-format.md` |
+
+## 失败经验分类
+
+Stop hook 写入 failed trace 摘要时，应尽量归入下面的分类，方便后续判断是补 truth source、补 hook、补子代理边界，还是只保留为一次性 trace。
+
+| 分类 | 典型信号 | 优先处理 |
+| --- | --- | --- |
+| `semantic_constraint_lost` | 字段口径、单位、禁止修改范围、兼容性约束只出现在聊天里，后续实现忘记 | 补 product/context/testing truth source 或 task 语义约束包 |
+| `truth_source_missing` | task 声明了需求、架构、测试或数据证据，但对应文件不存在或内容不足 | BLOCKED，先补 truth source |
+| `hook_gap` | 问题可被确定性检查发现，但当前 hook / `.rules` / verify 没拦住 | 补 hook、`.rules` 或 `tools/harness/verify.ps1` 检查 |
+| `subagent_context_overflow` | 主会话读取了大量日志、依赖树、数据样本、完整 Skill 流程，导致上下文污染 | 改为子代理读取并只返回摘要 |
+| `state_file_bloat` | `task.json` / `progress.txt` 过大、格式漂移或被 AI 手工整理 | 交给 `runtime.state_compaction` 或治理修复，不允许手工重排 |
+| `review_gate_gap` | Stage 1 / Stage 2 未覆盖的产品、设计、测试可信度或维护性问题 | 补 review prompt、测试矩阵或 qa contract |
+| `domain_rule_candidate` | 多次出现同类领域规范违规，但还不是通用项目硬规则 | 先沉淀到 domain docs / skill，再决定是否提升 |
+| `service_topology_gap` | 跨服务、契约、IDL、schema、上下游或外部系统影响面靠 AI 搜索和猜测 | 补 `.service-matrix/dependencies.yaml` 或等价拓扑 truth source |
+
+提升前必须回答：
+
+- 这是一次性任务问题，还是会跨任务重复？
+- 能否用 deterministic check 发现？
+- 是否需要进入 instruction chain，还是应下沉到 docs / skill / hook / `.rules`？
+- 是否有复验证据证明修复后不再复现？
+
+## 修复流程
+
+1. Stop hook 发现治理失败或 failed trace。
+2. `harness-governance-check.ps1` 输出 JSON findings，并把 failed trace 摘要写入本文件。
+3. Stop hook 返回 continuation JSON，阻断停止。
+4. 下一轮先读 `AGENTS.md`、本文件、`docs/harness/rule-governance.md`、`.codex/rules/agents.md`。
+5. 由 `harness-writer` 或 driver 修复对应路径。
+6. 运行 `tools/harness/verify.ps1` 和直接相关验证。
+7. 只有复验成立且可复用时，才把经验提升到对应正式文档。
+
+## Self-Refinement 提升路径
+
+Stop hook、review、用户纠正或 failed trace 发现的问题，不应只停留在本轮对话。按下面路径处理：
+
+| 信号 | 首选落点 | 何时升级 |
+| --- | --- | --- |
+| 一次性任务事实 | 当前 trace、`progress.txt`、任务相关 product / testing 文档 | 不升级 |
+| 可复用项目经验 | `docs/knowledge/experience/` 或 `docs/knowledge/guidelines/` | 复验后进入 `ARCHIVE-001` |
+| 反复出现的领域口径 | domain docs、service matrix、project skill | 多次任务引用且有证据 |
+| 可机械化检查 | hook、`.rules`、`tools/harness/verify.ps1`、CI、lint、contract test | 已有确定性失败样本和通过样本 |
+| 每次会话都必须遵守的硬规则 | `AGENTS.md` 或子目录 `AGENTS.md` | proven 级别或 maintainer 明确要求 |
+
+提升前必须保留原始证据路径、复验命令和失败样本。不能把单次用户偏好、一次性修复或未复验猜测直接提升为全局规则。
+
+## 自动记录区
+
+新的 Stop hook 经验会追加在此节之后。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/service-dependency-matrix.md

@@ -0,0 +1,55 @@
+# Service Dependency Matrix
+
+本文件说明 `.service-matrix/dependencies.yaml` 的维护口径。它是多服务、多仓库、IDL / API 契约或外部系统集成项目的可选 truth source；单体、小型前端或一次性脚本可以标记为 `not_applicable`。
+
+## 适用条件
+
+满足任一条件时，应启用服务依赖矩阵：
+
+- 一个需求会修改或影响多个服务、包、仓库、worker、前端应用或脚本入口。
+- 涉及 OpenAPI、protobuf、GraphQL schema、数据库 schema、消息事件、文件格式或第三方 API 契约。
+- 需要确认上游调用方、下游依赖方、灰度、回滚、兼容性或分支一致性。
+- 过去出现过“AI 只改了局部代码但漏掉调用链 / 契约 / 下游影响”的返工。
+
+## 维护原则
+
+- 矩阵只记录稳定拓扑和契约事实，不记录一次性任务过程。
+- 不把矩阵写成项目百科；每条依赖必须能回答“谁依赖谁、通过什么契约、变更时检查什么”。
+- 如果依赖需要人工确认，写 `status: needs-confirmation`，不得让实现任务继续猜。
+- 如果某个项目不需要矩阵，在 `docs/architecture/constraints.md` 中写明 `service_matrix: not_applicable`。
+
+## 最小字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `service_id` | 稳定服务、应用、包、worker 或集成名 |
+| `repo_path` | 当前仓库内路径或外部仓库标识 |
+| `entrypoints` | HTTP route、CLI command、worker、UI route、package export 等公开入口 |
+| `contracts` | OpenAPI、protobuf、GraphQL、typed API、schema、event、file format 或 `none` |
+| `upstream` | 调用本服务 / 包 / 入口的上游 |
+| `downstream` | 本服务 / 包 / 入口调用的下游 |
+| `change_gates` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
+| `owner` | 维护 owner 或确认人 |
+| `status` | `active` / `draft` / `needs-confirmation` / `deprecated` / `not_applicable` |
+
+## Driver 使用方式
+
+- `ANALYSIS` 阶段识别本轮需求是否需要服务矩阵；需要时补齐 `.service-matrix/dependencies.yaml`。
+- `PLAN` 阶段把受影响服务、契约和 change gates 映射到每个 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `feature_impl` 阶段不得新增未声明的跨服务影响；发现矩阵缺失或不可信时输出 `BLOCKED`。
+- `release` 阶段必须验证跨服务主链路、契约/API、失败态和回写证据。
+
+## Review 口径
+
+Stage 1 先检查矩阵是否足以支撑实现计划：
+
+- 受影响服务是否都已列出。
+- 上下游、契约、分支或版本约束是否明确。
+- 是否有未确认依赖被实现任务当成已确认事实。
+- 验证命令是否覆盖矩阵中的 change gates。
+
+Stage 2 再检查代码是否真的遵守矩阵：
+
+- 公开入口、契约、实现、测试和证据是否一致。
+- 是否漏改下游调用、mock、生成代码、schema 或配置。
+- 失败、回滚、兼容性和灰度路径是否有证据。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/speckit-requirements-gate.md

@@ -0,0 +1,260 @@
+# Speckit Requirements Gate
+
+本文件固化“模糊需求先澄清，再进入 spec / plan / task”的项目流程。
+
+## 1. 目标
+
+避免把 Agent 的推测写成项目真相源。用户只给出愿景、方向或不完整需求时，主会话必须进入 Speckit 需求澄清模式，而不是直接创建业务文档、测试矩阵或 `task.json` 实现任务。
+
+## 2. 触发条件
+
+满足任一条件即触发：
+
+- 用户只给出一句高层需求，例如“做一个跨端宠物商城 App”。
+- 平台、技术约束、MVP 范围、用户角色、核心流程、数据源或验收标准缺失。
+- 存在多个合理方向，且不同选择会影响页面、架构、测试或任务拆分。
+- 用户没有明确说明这是“先做原型 / spike / demo”，还是要按既定系统、既定开源栈和真实环境做正式集成。
+- 用户表达“先看看方案”“帮我规划”“需求还没想清楚”等探索意图。
+
+## 3. 清晰度分级
+
+| Level | 判定 | 允许动作 | 禁止动作 |
+| --- | --- | --- | --- |
+| `CLEAR` | 平台、范围、角色、主流程、数据源、验收标准都明确 | 运行 `speckit-specify`，进入 spec 验证和 plan | 跳过 spec 直接写实现任务 |
+| `PARTIAL` | 大方向明确，但仍有少量不影响主路径的缺口 | 生成 spec 草案，保留最多 3 个 `[NEEDS CLARIFICATION]` | 把草案同步成正式项目 docs |
+| `AMBIGUOUS` | 需求只有愿景或存在多个合理产品方向 | 进入 `speckit-clarify`，一次只问一个高影响问题 | 创建业务 docs、测试矩阵或 `task.json` 实现任务 |
+| `CONFLICTING` | 用户描述中存在互相冲突的目标、范围或约束 | 先让用户裁决冲突点 | 使用 Agent 假设消解冲突 |
+
+## 4. 必须使用的 Skill
+
+- `speckit-specify`: 从自然语言需求生成 feature spec 草案，允许最多 3 个 `[NEEDS CLARIFICATION]`。
+- `speckit-clarify`: 在进入 plan 前识别关键不确定点，一次只问一个问题，最多 5 个高影响澄清问题，并把答案写回 spec。
+- `speckit-plan`: 只有 spec 已确认且关键澄清完成后才能使用，用于技术计划与设计产物。
+
+## 5. Speckit 产物边界
+
+Speckit 产物和项目 Harness 产物必须分层：
+
+- `specs/<feature>/spec.md`: 需求草案和用户确认后的 feature spec。
+- `specs/<feature>/plan.md`: 技术计划和研究结论。
+- `specs/<feature>/research.md`: 主控自动查找的最佳实践、技术选择依据和替代方案。
+- `specs/<feature>/data-model.md` / `contracts/` / `quickstart.md`: plan 阶段派生设计产物。
+- `docs/product/*`、`docs/design/*`、`docs/testing/*`、`docs/context/*`: 只有用户确认 spec / plan 后，才允许从 Speckit 产物同步出的正式项目真相源。
+
+草案 spec 不得直接作为 driver 真相源。只有用户确认后的 spec / plan，以及由其同步出的项目 docs，才能进入 `task.json.context_files`。
+
+## 6. 允许与禁止
+
+允许：
+
+- 输出澄清选项。
+- 给出推荐选项及理由。
+- 维护临时草案或明确标注 `[NEEDS CLARIFICATION]` 的 spec。
+- 在用户回答后更新 spec 草案。
+- 在进入 `/speckit.plan` 前，先锁定当前 feature 的交付模式：`prototype` / `spike` / `integration` / `production`。
+
+禁止：
+
+- 在用户确认前创建 `docs/product/*`、`docs/design/*`、`docs/context/*` 作为正式真相源。
+- 在用户确认前把测试矩阵填成具体业务需求。
+- 在用户确认前新增 `task.json` 代码实现任务。
+- 把技术栈、页面范围、支付方式、后端模式等主观推测伪装成用户已确认需求。
+- 当需求里明确提到既定开源栈、外部系统或真实环境时，未获用户明确降级前，不得把本地 mock / sample adapter / 假数据方案当成正式集成默认值。
+
+## 7. 标准交互格式
+
+每次只问一个高影响问题。多选问题使用以下格式：
+
+```text
+**Recommended:** Option A - 选择它的原因。
+
+| Option | Choice | Impact |
+| --- | --- | --- |
+| A | 推荐方案 | 影响说明 |
+| B | 替代方案 | 影响说明 |
+| C | 替代方案 | 影响说明 |
+```
+
+如果需要一次性给用户预览全局选项，只能作为“下一步会逐项确认的选项地图”，不能视为已确认答案。
+
+## 8. 用户确认语义
+
+只有以下表达或同等明确授权，才视为用户确认 spec / plan：
+
+- “确认”
+- “按这个执行”
+- “进入下一步”
+- “生成任务”
+- “跑 driver”
+- “开始实现”
+
+以下表达不视为确认：
+
+- “看起来不错”
+- “继续聊聊”
+- “可以参考”
+- “再完善下”
+- “还有没有问题”
+
+如果确认语义不明确，主会话只允许继续完善 spec / plan，不得生成 `task.json` 实现任务。
+
+## 9. 交付模式锁定
+
+在 `/speckit.plan` 之前，必须把当前 feature 明确归入以下其中一种模式，并写入 `spec.md`：
+
+- `prototype`: 目标是本地原型或可演示界面，不承诺真实外部依赖已接通。
+- `spike`: 目标是探索性验证，用来缩小不确定性，不承诺正式需求完成。
+- `integration`: 目标是按既定开源栈、既定平台或真实下游完成集成。
+- `production`: 目标是正式交付，除真实集成外，还要满足生产级验证、证据和回归要求。
+
+锁定规则：
+
+- 只要用户明确提到既定开源栈、既有平台、第三方系统、真实 endpoint、RBAC、dashboard/panel、报警链路或环境接入，默认按 `integration` 理解，除非用户明确说“先只做原型 / demo / exploratory”。
+- `prototype` / `spike` 路径可以创建 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 类交付，不得直接冒充正式 `FR-*` 完成。
+- `integration` / `production` 路径必须在 `plan.md` 里补齐开源项目复用矩阵、connector 边界、前置阻塞 `TBD-*`、证据文件路径和验证分层，缺一不可。
+
+## 10. Spec 确认后的自动补齐规则
+
+用户确认 spec 后，后续问题默认不再回问用户。主控必须自动查找最佳实践、官方文档、项目约束和现有代码，补齐技术计划、设计细节、测试矩阵和任务拆分。
+
+为节省主控上下文，自动补齐不得默认由主控单线程完成。主控必须把 research、技术选型比较、测试规划、设计细化、审查和失败归因等上下文密集工作委派给子代理或拆成 driver 任务；主控只接收结构化摘要、决策依据、文件路径和验证命令。
+
+自动补齐优先级：
+
+1. 已确认的 `specs/<feature>/spec.md`。
+2. 用户在 Clarifications 中给出的答案。
+3. 项目规则：`AGENTS.md`、`docs/harness/*`、`.codex/task-run-profile.json`。
+4. 已存在代码、配置和测试约定。
+5. 官方文档、框架最佳实践和安全/可访问性通用规范。
+
+只有以下情况允许重新询问用户：
+
+- 需要业务裁决，且多个选择会改变产品范围或收费/合规/品牌承诺。
+- 需要真实外部凭据、账号、密钥、支付商户号或第三方服务授权。
+- 用户之前确认的 spec 与后续新增要求发生冲突。
+- 自动查到的最佳实践之间存在重大取舍，且取舍会影响用户业务目标。
+
+如果只是技术实现细节、目录结构、测试工具、默认 UI 状态、错误处理策略或工程最佳实践，主控应自行决策并在 `research.md` / `plan.md` 中记录依据。
+
+## 10.1 需求增强与缺口阻塞
+
+`speckit-specify` 生成初稿后，进入 `speckit-plan` 或写入真实 `task.json` 前，必须执行一次需求增强扫描。该扫描不是可选润色，而是阻止“需求给到了但细节没补全”的硬门禁。
+
+需求增强扫描必须把需求分成三类：
+
+- `Explicit`: 用户原文明确写出的需求，不得改写含义。
+- `Inferred`: 可由业务上下文、工程最佳实践、平台常规行为或现有项目约束合理推出的隐式需求，必须写入 `Assumptions`、NFR、验收标准或测试矩阵。
+- `Decision Required`: 会改变业务范围、收费、合规、品牌承诺、真实外部依赖或用户体验主路径的缺口，必须写入 `[NEEDS CLARIFICATION]`、`Open Questions` 或 `TBD-*`，不得假装已确认。
+
+自动补齐至少覆盖：
+
+- 功能细节：角色、主流程、失败流、边界条件、空态、重复提交、取消/回退、权限拒绝、非法状态和副作用/无副作用。
+- UI 细节：default、loading、empty、error、permission_denied、disabled、long_content、mobile，以及截图或视觉验收证据。
+- API / 后端细节：参数校验、错误码、权限、幂等、数据生命周期、状态机、审计日志和异步任务可观测性。
+- 非功能需求：性能、安全、隐私、可访问性、兼容性、可用性、可观测性、数据一致性、备份/恢复、部署和运维约束；不适用时必须写明原因。
+- 测试与证据：正向、失败、边界、权限、状态流转、测试数据、可观察 Oracle、证据路径和 release impact。
+
+允许自动决策的内容：
+
+- 技术实现细节、目录结构、测试工具选择、错误展示默认策略、常见 UI 状态、通用安全基线和工程最佳实践。
+- 自动决策必须记录为 `Assumption`，并带有验证方式和“假设错误时影响”。
+
+必须回问或阻塞的内容：
+
+- 业务范围裁决、付费/结算/合规承诺、真实凭据/账号/密钥、第三方授权、品牌/法务口径、用户明确要求的外部系统行为。
+- 对 `integration` / `production` 模式，如果缺少真实 endpoint、RBAC、fixture、dashboard/panel、webhook 或证据环境，相关需求不得标记为 `Ready`。
+
+需求增强必须产出或更新 `specs/<feature>/requirements-enrichment.md`，最少包含：
+
+- `显式需求清单`
+- `自动推导需求清单`
+- `自动补齐的 NFR`
+- `Assumptions`
+- `Decision Required / Open Questions`
+- `Blocked Items`
+- `P0/P1 可测试性状态表`
+
+如果任一 P0/P1 需求缺少验收标准、测试数据、Oracle、证据路径或可执行验证方式，状态必须是 `Needs Clarification` 或 `Blocked`，不得进入 `feature_impl`。
+
+推荐委派边界：
+
+- `readonly-research`: 官方文档、框架最佳实践、安全/可访问性通用规范。
+- `requirements-trace-analyst`: spec 到页面、状态、数据、验收的追溯。
+- `test-runner` / `test-planner`: test matrix、E2E plan、seed data、failure triage。
+- `visual-reviewer` / `design-lead`: design brief、component map、screen states、visual parity plan。
+- `stage1-reviewer` / `stage2-reviewer`: spec 一致性和质量门禁。
+
+子代理只返回高密度结果，不返回完整阅读材料。主控不得把子代理的完整 transcript 重新塞回主上下文。
+
+## 11. 跳过澄清与原型例外
+
+如果用户要求跳过澄清，必须在回复和 spec 中记录：
+
+- 用户选择跳过澄清。
+- 哪些高影响问题仍未确认。
+- 后续实现可能返工的范围。
+
+跳过澄清后只能创建 `spike` / `prototype` / `exploratory` 类任务，不能创建 production-ready 实现任务，除非用户明确接受范围不稳定和返工风险。
+
+如果用户明确说“直接做原型 / 先出 demo / 不要问”，允许进入原型路径，但任务必须标注：
+
+- `task_kind`: `prototype` 或 `spike`
+- `gate_profile`: `exploratory`
+- acceptance 中明确“不代表生产范围已确认”
+- 不得把演示型 deliverable 直接记为正式 `FR-*` 完成；要么改成 `PROTO-*` / `SPIKE-*` / `INTEGRATION-*`，要么明确记录哪些 `FR-*` 仍处于未完成集成态
+
+## 12. Demo-first 默认路径
+
+对有界面、流程或客户演示价值的产品，用户确认 spec / plan 后默认走 Demo-first 路径：
+
+1. 先完成 `ANALYSIS-001`，把 P0/P1 需求映射到页面、状态、数据和验收。
+2. 再完成 `DESIGN-001` 和 `DESIGN-ASSET-001`，把界面规格、状态矩阵和 UI 参考图落成可编码真相源。
+3. `PLAN-001` 必须先锁定 `DEMO-001` 的范围、运行命令、mock 数据边界和人工介入点。
+4. `DEMO-001` 用 mock 数据跑通可点击体验，记录启动命令、访问地址、已知问题和不接真实环境的边界。
+5. 正式 foundation / domain / verify 任务必须依赖 `DEMO-001`，不能跳过 Demo 直接进入后端、支付、推送、真实登录或生产级部署。
+
+`DEMO-001` 通过不代表生产就绪。它只证明核心流程能被用户体验和评审；真实接口、真实支付、真实设备、上架审核、安全合规仍要在后续正式任务中验证。
+
+## 13. 写入 task.json 前检查
+
+生成真实实现任务前必须全部满足：
+
+- `specs/<feature>/spec.md` 存在。
+- spec 中无会影响范围、架构、测试或 UX 的未解决 `[NEEDS CLARIFICATION]`。
+- 用户确认语义明确，或已记录跳过澄清的风险和原型降级。
+- `speckit-plan` 已生成 plan / research，或项目 docs 中已有等价技术计划。
+- 正式项目真相源已从确认后的 spec / plan 同步。
+- P0/P1 需求已映射到页面、状态、数据、验收和测试。
+- 对既定开源栈或外部系统的需求，已明确锁定 `prototype` / `spike` / `integration` / `production` 模式。
+- 若模式为 `integration` / `production`，`plan.md` 已包含开源项目复用矩阵、前置阻塞 `TBD-*`、connector 分层和证据路径。
+- `task.json` 新任务只引用确认后的 truth sources。
+- 对 UI / App / Web / 小程序 / 客户演示类项目，任务队列包含 `DEMO-001`，且正式实现任务依赖它。
+
+## 14. 状态流转
+
+```text
+模糊需求
+  -> 读取 speckit-specify / speckit-clarify skill
+  -> 判定 CLEAR / PARTIAL / AMBIGUOUS / CONFLICTING
+  -> 识别缺口与高影响决策
+  -> 若涉及既定 OSS / 外部系统，先锁定 prototype vs real integration
+  -> 一次一个问题收集用户选择
+  -> 更新 specs/<feature>/spec.md 与 Clarifications
+  -> 用户确认 spec
+  -> 主控委派子代理查找最佳实践并执行 speckit-plan
+  -> 从确认后的 spec / plan 同步项目设计与测试文档
+  -> 先写入 Demo-first 队列并跑通 DEMO-001
+  -> 写入 task.json
+  -> tools/harness/codex-loop.ps1
+```
+
+## 15. 完成标准
+
+进入 `task.json` 前必须满足：
+
+- spec 中没有会影响范围、架构、测试或用户体验的未解决 `[NEEDS CLARIFICATION]`。
+- 用户已明确确认 spec 或明确接受跳过澄清的返工风险。
+- P0/P1 需求能映射到页面、状态、数据、验收和测试。
+- plan 已说明技术栈、验证命令、依赖和任务边界。
+- 若需求涉及既定开源栈或真实外部系统，spec 已锁定交付模式，plan 已补齐复用矩阵、阻塞项和证据路径。
+- 若项目有界面或客户演示价值，任务队列已明确 Demo-first 依赖：`DESIGN-ASSET-001` -> `PLAN-001` -> `DEMO-001` -> 正式实现。

package/package-source/docs/codex-harness-engineering/templates/package-assets/root/PACKAGE.md

@@ -0,0 +1,49 @@
+# Codex Harness Package
+
+## Mode Policy
+
+当前包默认使用 thin project 安装语义：无 `-Mode` / `-Scope` 时，`tools/install/install-agent.ps1 -ProjectRoot .` 等价于 `-Scope project`，初始化项目运行必需的 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/` 和 `tools/`。
+
+保留的入口：
+
+- `-Scope project`：新默认 thin project 入口，保留瘦的项目级 `.agents/skills/`、`.agents/workflows/`，不复制完整 vendor 镜像、legacy docs 或 package template source。
+- `-Scope user`：只安装用户级 codex-harness package source 和用户级 package lock，不暴露全局 `.agents/skills/` / `.agents/workflows/`。
+- `-Scope vendor`：显式 vendor 入口，只复制项目内 `.agents/` vendor 包，适合离线或强隔离项目。
+- `-Mode full`：显式 legacy full 兼容入口，同时输出项目 runtime、完整 `.agents/` vendor 包和 legacy docs。
+- `-Mode project|vendor|user`：保留旧兼容入口；新项目优先使用 `-Scope user|project|vendor`。
+
+默认 thin project 不会自动删除旧项目已有 `.agents/` 或 legacy docs。旧项目迁移前先运行 `-MigratePlan`，确认后再运行 `-MigrateApply -Confirm`；也可以显式保留 `-Scope vendor` / `-Mode full`。
+
+## Install
+
+新项目默认安装：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+```
+
+显式 thin project：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope project
+```
+
+显式 legacy full：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
+```
+
+显式 vendor：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
+```
+
+## Smoke
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
+```
+
+该 smoke 覆盖默认 thin project、显式 legacy full、`-Scope project`、`-Scope vendor`、`-Scope user` 和 legacy plan 兼容入口。

package/package-source/docs/codex-harness-engineering/templates/package-assets/root/README.md

@@ -0,0 +1,52 @@
+# Codex Harness Agent Package
+
+本包默认使用方案 A 的极简根目录布局。安装后目标项目使用 `task.json + tools/harness/codex-loop.ps1` 作为自动执行入口，driver 负责选择任务、运行验证、写 trace、更新进度和提交结果。
+
+SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。
+
+## 安装
+
+从包含 当前仓库包根目录的项目父目录运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+```
+
+从已安装的 `.agents/` 自更新：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
+```
+
+## 安装产物
+
+- 项目根 `AGENTS.md`
+- `tools/harness/` 下的 `tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`
+- `tools/install/` 下的 `tools/install/bootstrap-codex-harness.ps1`、`tools/install/env-check.ps1`、安装脚本
+- 项目根 `task.json`、`progress.txt`
+- `tools/harness/templates/` 下的 `smoke-task.json`、`tools/harness/templates/project-task-template.json`
+- `docs/harness/trace.schema.json`
+- 项目根 `.codex/`
+- 项目根 `docs/harness/`、`docs/testing/`
+- 项目根 `.agents/` 完整能力包，包括 rules、skills、workflows、`.specify/` 和模板复制源
+
+## 使用顺序
+
+1. 读取项目根 `AGENTS.md`。
+2. 用 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*` 收敛项目上下文。
+3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
+4. 将确认后的任务写入 `task.json`。
+5. 运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/verify.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1
+```
+
+## 验证安装包
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
+```
+
+该脚本现在只验证 full 安装形状。