@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/external-knowledge/integration-roadmap.md

@@ -1,221 +1,221 @@
-# 外挂总知识库落地路线
-
-## 阶段 0：研究和边界冻结
-
-目标：先把“外挂总知识库是什么、不是什么”说清楚。
-
-产物：
-
-- `docs/external-knowledge/README.md`
-- `docs/external-knowledge/architecture.md`
-- `docs/external-knowledge/initial-content.md`
-- `docs/external-knowledge/integration-roadmap.md`
-
-验收：
-
-- 明确项目知识与外挂知识的优先级。
-- 明确第一版不依赖 RAG。
-- 明确外部知识不可用时不阻塞本地 driver。
-- 明确长文档必须通过 catalog 进入查询链路，不进入默认上下文。
-
-## 阶段 1：完整项目 MVP 骨架
-
-目标：创建 `team-wiki/` 独立仓库，并从一开始按完整项目管理，而不是只建文档目录。
-
-任务：
-
-1. 按 `initial-content.md` 创建目录。
-2. 创建 `knowledge-catalog.md`、`.knowledge-config.yaml`、`log.md`。
-3. 创建 `quality-management/`、`software-engineering/`、`agent-engineering/` 三大知识域。
-4. 创建 `schemas/` 和 `scripts/`，至少预留 frontmatter schema 与 lint 脚本入口。
-5. 创建 `contributions/pending/`、`contributions/conflicts/`、`reports/` 和 `archive/`。
-6. 写入 10-20 条面向 AI 编程质量管理和软件工程的 draft 种子知识。
-7. 为每条种子知识补齐 frontmatter。
-
-建议验证：
-
-```powershell
-git diff --check
-```
-
-后续可增加：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File scripts/knowledge/lint-knowledge.ps1
-```
-
-## 阶段 2：项目侧外挂配置
-
-目标：让项目能声明外挂知识库位置，但不强依赖。
-
-新增项目文件：
-
-```text
-.knowledge-sources.yml
-```
-
-最小内容：
-
-```yaml
-schema_version: 1
-sources:
-  project:
-    path: docs/knowledge
-    required: true
-  team:
-    path: ../team-wiki
-    required: false
-    catalogs:
-      - knowledge-catalog.md
-      - quality-management/catalog.md
-      - software-engineering/catalog.md
-      - agent-engineering/catalog.md
-      - app/catalog.md
-query:
-  max_catalogs: 4
-  max_entries: 8
-  prefer_maturity: [proven, verified, draft]
-```
-
-任务：
-
-1. 在 Harness 模板中加入 `.knowledge-sources.yml` 示例。
-2. 在 `tools/harness/templates/project-task-template.json.runtime.handoff.truth_sources` 中支持 `team_knowledge`。
-3. `team_knowledge` 缺失时只输出 warning。
-4. 项目画像 `project-profiles/<project-slug>.md` 可选接入，用于过滤不相关知识。
-5. 领域扩展 catalog，如 `common/catalog.md`、`app/catalog.md`，只有任务命中对应 AI Coding 控制、平台或发布风险时才读取。
-
-## 阶段 3：Prompt 查询协议
-
-目标：让 Codex 会话知道何时读取外挂知识。
-
-修改点：
-
-- `implement-one-task.md`
-- `review-stage1-spec.md`
-- `review-stage2-quality.md`
-- `failure-triage.md`
-- `repair-one-finding.md`
-- `worker-role/*`
-
-要求：
-
-1. 先读项目 truth source。
-2. 再读项目 `docs/knowledge/knowledge-catalog.md`。
-3. 如 `.knowledge-sources.yml` 存在且任务相关，再读外挂 catalog。
-4. 只读取少量相关条目。
-5. 最终输出 `knowledge_references` 时标记来源：
-6. 对 `common/`、`app/` 这类长文档领域扩展，先读 catalog 摘要；只有 AI Coding 生产控制、移动端上线、平台审核、支付、隐私、安全、弱网、灰度回滚或行业专项任务才读取完整规范相关章节。
-
-```markdown
-## Knowledge References
-- `GUIDELINE-HARNESS-001`: title - source=team - used_in=plan - `../team-wiki/...`
-```
-
-## 阶段 4：同步候选任务
-
-目标：把项目知识中可复用的 verified/proven 候选导出到外挂库 pending。
-
-新增可选任务：
-
-```json
-{
-  "id": "KNOWLEDGE-TEAM-SYNC-001",
-  "description": "把项目知识中的跨项目候选导出到外挂总知识库 pending",
-  "task_kind": "archive",
-  "phase": "archive",
-  "gate_profile": "lightweight",
-  "required_truth_sources": ["knowledge"],
-  "priority": 95,
-  "dependencies": ["ARCHIVE-001"],
-  "passes": false,
-  "context_files": [
-    ".knowledge-sources.yml",
-    "docs/harness/team-knowledge-sync.md",
-    "docs/knowledge/knowledge-catalog.md",
-    "docs/knowledge/catalog.md"
-  ],
-  "owned_paths": [
-    "docs/knowledge/"
-  ],
-  "execution": { "mode": "single" },
-  "test_command": "git diff --check",
-  "acceptance": [
-    "输出 team sync candidates 或说明外挂知识库不可用",
-    "没有把 draft 或单次经验直接升级为 proven",
-    "冲突只进入 conflict candidate，不覆盖外挂知识主干"
-  ]
-}
-```
-
-如果需要直接写外挂仓库，必须显式把外挂路径纳入 owned paths 或由人工执行同步。
-
-## 阶段 5：最小脚本
-
-建议新增脚本：
-
-```text
-scripts/knowledge/
-  resolve-sources.ps1
-  lint-knowledge.ps1
-  export-team-candidates.ps1
-  build-agent-index.ps1
-```
-
-职责：
-
-- `resolve-sources.ps1`：读取 `.knowledge-sources.yml`，输出可用 catalog 和缺失 source。
-- `lint-knowledge.ps1`：检查 frontmatter、catalog、孤儿条目、重复和冲突候选。
-- `export-team-candidates.ps1`：把项目 promotion candidates 转成 `contributions/pending/` 条目。
-- `build-agent-index.ps1`：生成 `agent-context.md` 或 `llms.txt` 形式的低成本 Agent 查询入口。
-
-脚本边界：
-
-- 不自动删除知识。
-- 不静默提升为 `proven`。
-- 外挂库不可用时 exit 0 + warning，除非用户显式要求强制同步。
-
-## 阶段 6：RAG 增强
-
-触发条件：
-
-- 外挂知识超过 300 条。
-- catalog 筛选已经不足以召回相关内容。
-- 已有稳定 frontmatter 和权限边界。
-
-RAG 结构：
-
-```text
-Markdown Git repo
-  -> index builder
-  -> vector store
-  -> retrieval candidates
-  -> 回到 Markdown source 读取原文
-```
-
-RAG 不作为 truth source。它只负责召回候选，最终引用必须指向 Git 中的 Markdown 条目。
-
-## 风险和防线
-
-| 风险 | 防线 |
-| --- | --- |
-| 外挂知识覆盖项目事实 | 项目 truth source 优先，冲突输出 candidate |
-| 知识库膨胀 | catalog-first、query budget、lint |
-| 单次经验变全局规则 | draft 默认、proven 需多证据或审批 |
-| 外部库不可用阻塞开发 | `required: false`，降级 warning |
-| 过时知识误导 Agent | last_referenced、decay、archive |
-| 泄露敏感信息 | 禁止 token、cookie、私钥、客户数据入库 |
-
-## 第一轮实施建议
-
-先做以下最小闭环：
-
-1. 创建独立 `team-wiki` 仓库骨架。
-2. 按质量管理、软件工程、Agent 工程三大域写入 10-20 条种子知识。
-3. 在本项目新增 `.knowledge-sources.yml` 示例。
-4. 修改 prompt，让它能按需读取外挂 catalog。
-5. 新增 `resolve-sources.ps1` 和 `lint-knowledge.ps1`。
-6. 跑一次人工 ARCHIVE，把当前 Harness 的两条 draft 项目知识导出为团队 pending 候选。
-7. 将 `docs/external-knowledge/common/catalog.md` 作为通用 AI Coding 生产控制入口，将 `docs/external-knowledge/app/catalog.md` 作为 App 生产可上线领域扩展入口，并保持完整规范为按需读取资料。
-
-这一步完成后，再考虑自动同步和 RAG。
+# 外挂总知识库落地路线
+
+## 阶段 0：研究和边界冻结
+
+目标：先把“外挂总知识库是什么、不是什么”说清楚。
+
+产物：
+
+- `docs/external-knowledge/README.md`
+- `docs/external-knowledge/architecture.md`
+- `docs/external-knowledge/initial-content.md`
+- `docs/external-knowledge/integration-roadmap.md`
+
+验收：
+
+- 明确项目知识与外挂知识的优先级。
+- 明确第一版不依赖 RAG。
+- 明确外部知识不可用时不阻塞本地 driver。
+- 明确长文档必须通过 catalog 进入查询链路，不进入默认上下文。
+
+## 阶段 1：完整项目 MVP 骨架
+
+目标：创建 `team-wiki/` 独立仓库，并从一开始按完整项目管理，而不是只建文档目录。
+
+任务：
+
+1. 按 `initial-content.md` 创建目录。
+2. 创建 `knowledge-catalog.md`、`.knowledge-config.yaml`、`log.md`。
+3. 创建 `quality-management/`、`software-engineering/`、`agent-engineering/` 三大知识域。
+4. 创建 `schemas/` 和 `scripts/`，至少预留 frontmatter schema 与 lint 脚本入口。
+5. 创建 `contributions/pending/`、`contributions/conflicts/`、`reports/` 和 `archive/`。
+6. 写入 10-20 条面向 AI 编程质量管理和软件工程的 draft 种子知识。
+7. 为每条种子知识补齐 frontmatter。
+
+建议验证：
+
+```powershell
+git diff --check
+```
+
+后续可增加：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/knowledge/lint-knowledge.ps1
+```
+
+## 阶段 2：项目侧外挂配置
+
+目标：让项目能声明外挂知识库位置，但不强依赖。
+
+新增项目文件：
+
+```text
+.knowledge-sources.yml
+```
+
+最小内容：
+
+```yaml
+schema_version: 1
+sources:
+  project:
+    path: docs/knowledge
+    required: true
+  team:
+    path: ../team-wiki
+    required: false
+    catalogs:
+      - knowledge-catalog.md
+      - quality-management/catalog.md
+      - software-engineering/catalog.md
+      - agent-engineering/catalog.md
+      - app/catalog.md
+query:
+  max_catalogs: 4
+  max_entries: 8
+  prefer_maturity: [proven, verified, draft]
+```
+
+任务：
+
+1. 在 Harness 模板中加入 `.knowledge-sources.yml` 示例。
+2. 在 `tools/harness/templates/project-task-template.json.runtime.handoff.truth_sources` 中支持 `team_knowledge`。
+3. `team_knowledge` 缺失时只输出 warning。
+4. 项目画像 `project-profiles/<project-slug>.md` 可选接入，用于过滤不相关知识。
+5. 领域扩展 catalog，如 `common/catalog.md`、`app/catalog.md`，只有任务命中对应 AI Coding 控制、平台或发布风险时才读取。
+
+## 阶段 3：Prompt 查询协议
+
+目标：让 Codex 会话知道何时读取外挂知识。
+
+修改点：
+
+- `implement-one-task.md`
+- `review-stage1-spec.md`
+- `review-stage2-quality.md`
+- `failure-triage.md`
+- `repair-one-finding.md`
+- `worker-role/*`
+
+要求：
+
+1. 先读项目 truth source。
+2. 再读项目 `docs/knowledge/knowledge-catalog.md`。
+3. 如 `.knowledge-sources.yml` 存在且任务相关，再读外挂 catalog。
+4. 只读取少量相关条目。
+5. 最终输出 `knowledge_references` 时标记来源：
+6. 对 `common/`、`app/` 这类长文档领域扩展，先读 catalog 摘要；只有 AI Coding 生产控制、移动端上线、平台审核、支付、隐私、安全、弱网、灰度回滚或行业专项任务才读取完整规范相关章节。
+
+```markdown
+## Knowledge References
+- `GUIDELINE-HARNESS-001`: title - source=team - used_in=plan - `../team-wiki/...`
+```
+
+## 阶段 4：同步候选任务
+
+目标：把项目知识中可复用的 verified/proven 候选导出到外挂库 pending。
+
+新增可选任务：
+
+```json
+{
+  "id": "KNOWLEDGE-TEAM-SYNC-001",
+  "description": "把项目知识中的跨项目候选导出到外挂总知识库 pending",
+  "task_kind": "archive",
+  "phase": "archive",
+  "gate_profile": "lightweight",
+  "required_truth_sources": ["knowledge"],
+  "priority": 95,
+  "dependencies": ["ARCHIVE-001"],
+  "passes": false,
+  "context_files": [
+    ".knowledge-sources.yml",
+    "docs/harness/team-knowledge-sync.md",
+    "docs/knowledge/knowledge-catalog.md",
+    "docs/knowledge/catalog.md"
+  ],
+  "owned_paths": [
+    "docs/knowledge/"
+  ],
+  "execution": { "mode": "single" },
+  "test_command": "git diff --check",
+  "acceptance": [
+    "输出 team sync candidates 或说明外挂知识库不可用",
+    "没有把 draft 或单次经验直接升级为 proven",
+    "冲突只进入 conflict candidate，不覆盖外挂知识主干"
+  ]
+}
+```
+
+如果需要直接写外挂仓库，必须显式把外挂路径纳入 owned paths 或由人工执行同步。
+
+## 阶段 5：最小脚本
+
+建议新增脚本：
+
+```text
+scripts/knowledge/
+  resolve-sources.ps1
+  lint-knowledge.ps1
+  export-team-candidates.ps1
+  build-agent-index.ps1
+```
+
+职责：
+
+- `resolve-sources.ps1`：读取 `.knowledge-sources.yml`，输出可用 catalog 和缺失 source。
+- `lint-knowledge.ps1`：检查 frontmatter、catalog、孤儿条目、重复和冲突候选。
+- `export-team-candidates.ps1`：把项目 promotion candidates 转成 `contributions/pending/` 条目。
+- `build-agent-index.ps1`：生成 `agent-context.md` 或 `llms.txt` 形式的低成本 Agent 查询入口。
+
+脚本边界：
+
+- 不自动删除知识。
+- 不静默提升为 `proven`。
+- 外挂库不可用时 exit 0 + warning，除非用户显式要求强制同步。
+
+## 阶段 6：RAG 增强
+
+触发条件：
+
+- 外挂知识超过 300 条。
+- catalog 筛选已经不足以召回相关内容。
+- 已有稳定 frontmatter 和权限边界。
+
+RAG 结构：
+
+```text
+Markdown Git repo
+  -> index builder
+  -> vector store
+  -> retrieval candidates
+  -> 回到 Markdown source 读取原文
+```
+
+RAG 不作为 truth source。它只负责召回候选，最终引用必须指向 Git 中的 Markdown 条目。
+
+## 风险和防线
+
+| 风险 | 防线 |
+| --- | --- |
+| 外挂知识覆盖项目事实 | 项目 truth source 优先，冲突输出 candidate |
+| 知识库膨胀 | catalog-first、query budget、lint |
+| 单次经验变全局规则 | draft 默认、proven 需多证据或审批 |
+| 外部库不可用阻塞开发 | `required: false`，降级 warning |
+| 过时知识误导 Agent | last_referenced、decay、archive |
+| 泄露敏感信息 | 禁止 token、cookie、私钥、客户数据入库 |
+
+## 第一轮实施建议
+
+先做以下最小闭环：
+
+1. 创建独立 `team-wiki` 仓库骨架。
+2. 按质量管理、软件工程、Agent 工程三大域写入 10-20 条种子知识。
+3. 在本项目新增 `.knowledge-sources.yml` 示例。
+4. 修改 prompt，让它能按需读取外挂 catalog。
+5. 新增 `resolve-sources.ps1` 和 `lint-knowledge.ps1`。
+6. 跑一次人工 ARCHIVE，把当前 Harness 的两条 draft 项目知识导出为团队 pending 候选。
+7. 将 `docs/external-knowledge/common/catalog.md` 作为通用 AI Coding 生产控制入口，将 `docs/external-knowledge/app/catalog.md` 作为 App 生产可上线领域扩展入口，并保持完整规范为按需读取资料。
+
+这一步完成后，再考虑自动同步和 RAG。

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

@@ -1,83 +1,95 @@
-# 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。
-- 完成声明能说明声明交付路径、测试替身和不适用边界。
+# 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`
+
+## 4.1 Backend Layering And Error Boundary
+
+如果项目包含后端服务、BFF、worker API 或命令式写路径，至少补齐：
+
+- `controller_policy`: Controller / Handler 只负责请求解析、权限入口、调用 service、响应映射；不堆业务规则。
+- `service_policy`: Service 负责业务逻辑、事务编排、幂等和副作用协调；不得直接依赖 `req/res/ctx/request/response`。
+- `repository_policy_detail`: Repository / DAO 负责数据库访问、查询组合和持久化边界；不返回页面展示字段。
+- `dto_policy`: DTO / Request / Response / Entity 的边界和禁止混用规则。
+- `error_handling_policy`: 全局异常处理、错误码模型、用户可见错误、日志保留策略。
+- `transaction_boundary`: 哪些写路径必须事务化，哪些步骤不得跨外部调用长持锁。
+- `idempotency_policy`: 哪些入口必须幂等，幂等键放在哪里，重复请求返回什么。
+
+## 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。
+- 完成声明能说明声明交付路径、测试替身和不适用边界。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/code-semantics-and-navigation.md

@@ -0,0 +1,17 @@
+# 代码语义与导航层
+
+本文定义项目里的导航顺序，帮助 agent 先找到入口，再进入具体实现。
+
+## 默认顺序
+
+1. `docs/ai/repo-map.md`
+2. `docs/ai/architecture-brief.md`
+3. `docs/ai/CURRENT_TASK.md`
+4. 代码语义工具或全文搜索
+5. `docs/knowledge/*`
+
+## 职责边界
+
+- `docs/ai/*`: 文档导航层
+- 代码语义工具: 定义、引用、调用链、影响面
+- `docs/knowledge/*`: 历史经验和长期可复用知识