@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/external-knowledge/common/catalog.md

@@ -0,0 +1,34 @@
+# 通用 AI Coding 生产控制知识入口
+
+本 catalog 用于按需加载 `common/` 下的通用 AI 编程生产控制资料。项目事实、PRD、架构约束、测试矩阵和当前 `task.json` 始终优先于本目录内容。
+
+## 使用规则
+
+1. 先读本 catalog，不要默认把完整长文档放进每轮上下文。
+2. 当前任务涉及 AI 生成代码治理、任务拆分、架构边界、接口契约、Review Gate、Release Gate、安全/隐私/依赖风险或生产交付控制时，再读取对应条目。
+3. 外部知识只能补充 checklist 和风险识别，不能覆盖项目 truth source。
+4. 采纳本目录内容后，应在 trace 或最终报告的 `knowledge_references` 中记录引用。
+
+## 条目索引
+
+| 条目 | 路径 | 适用阶段 | 读取触发 |
+| --- | --- | --- | --- |
+| AI Coding Production Control Framework | `common/AI_Coding_Production_Control_Framework_AI写完的代码如何不失控.md` | analysis / plan / implement / review / release | 需要控制 AI 代码失控风险、补齐架构/模式/实现三层约束、设计高风险人工 Review、定义 Release Gate 或 PR/Review 模板 |
+
+## 可吸收检查项
+
+| 主题 | 当前项目落点 |
+| --- | --- |
+| 三层控制模型 | `docs/architecture/constraints.md`、`task.json.architecture_constraints`、Stage 1 Review |
+| 任务边界 | `owned_paths`、`context_files`、`forbidden_implementations` |
+| 契约与验收 | `docs/testing/TRACEABILITY_MATRIX.md`、`qa_contract`、`test_command` |
+| 证据留存 | `traces/`、`progress.txt`、`docs/testing/EVIDENCE_PROTOCOL.md` |
+| 高风险 Review | `security-reviewer`、Stage 2 Review、任务级风险字段或人工确认项 |
+| Release Gate | `release` 任务、P0/P1 回归、跨故事整链路和 fresh evidence |
+
+## 不要直接吸收的内容
+
+- 不把全文搬进 `AGENTS.md`。
+- 不用通用 React/Python 示例覆盖具体项目技术栈。
+- 不把一次性经验直接升级为 proven 级规则。
+- 不把外部文档里的模板字段当成当前项目已确认事实。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/external-knowledge/initial-content.md

@@ -0,0 +1,296 @@
+# 外挂总知识库初始内容
+
+外挂总知识库最初必须先设定目录、元数据和种子内容，否则后续会变成散乱文档堆。第一版不追求内容多，重点是覆盖 Agent 高频决策面。
+
+## 初始内容原则
+
+- 每个条目必须能指导任务决策、实现、评审或验证。
+- 每个条目必须带 `source_references`，没有来源的经验只进入 `draft`。
+- 每个条目必须声明适用阶段和不适用边界。
+- 初始内容以 `draft` 为主，除非已有多项目证据或人工审批。
+- 不搬运完整文档，只抽取可执行判断。
+- GitHub、官方文档和公开文章只能用于调研和提炼模式，不直接复制原文。
+
+## 知识来源优先级
+
+基础通用知识不是从 GitHub 直接复制出来的。它应该来自可授权、可追溯、可验证的来源，并由 Codex 或维护者改写为团队自己的短条目。
+
+| 来源 | 应收集什么 | 使用方式 | 风险控制 |
+| --- | --- | --- | --- |
+| 团队真实项目经验 | trace、review finding、bug 修复、部署失败、测试缺口、事故复盘 | 作为最优先来源，初始为 `draft`，复用验证后升级 | 必须保留项目、任务、commit 或 trace 引用 |
+| 官方文档和标准 | 框架推荐做法、语言规范、安全标准、测试工具规则 | 摘要关键判断并链接来源，不复制全文 | 标明版本、适用范围和不适用条件 |
+| 优秀开源项目实践 | 目录结构、测试策略、CI、ADR、issue 模板、贡献流程 | 借鉴模式并重写为通用经验 | 不复制代码和文档原文，不照搬项目私有命令 |
+| 公开文章和案例 | 工程复盘、架构讨论、经验总结 | 作为候选启发，不作为强约束 | 初始只能是 `draft`，需要后续项目验证 |
+| 人工访谈和团队约定 | 业务规则、历史坑、团队偏好、内部流程 | 记录来源人、日期和适用项目 | 没有验证前不能升级为 `proven` |
+
+## 首批内容范围
+
+第一批只收 Agent 开发最容易影响成败的通用知识，不做百科全书。
+
+| 分类 | 首批应包含 | 不应包含 |
+| --- | --- | --- |
+| `quality-management/requirements-quality` | 需求可测试性、验收标准、Requirement ID、追溯矩阵、防止 AI 扩 scope | 泛产品方法论长文 |
+| `quality-management/verification-engineering` | `git diff --check` 边界、feature_impl 真实验证、affected tests、mock/test double 使用边界 | 只适用于单个测试框架的长教程 |
+| `quality-management/review-gates` | Stage 1/2 分工、finding 格式、repair queue、复验规则 | 只看代码风格的 checklist |
+| `software-engineering/task-decomposition` | task.json 拆分、owned paths、dependencies、单任务闭环 | 当前项目一次性路径 |
+| `software-engineering/architecture-constraints` | 架构约束包字段、交付形态、公开入口、数据边界、异步边界、`not_applicable` 规则 | 某个项目的部署拓扑细节 |
+| `software-engineering/integration-quality` | contract first、真实依赖、mock 切真实接口、联调证据 | 未验证的集成偏好 |
+| `agent-engineering/workflow-control` | driver-first、truth source、BLOCKED 协议、不伪造状态 | 聊天偏好 |
+| `agent-engineering/prompt-and-rule-governance` | AGENTS/prompt/template 写入边界、何时升级规则、敏感信息禁令 | 未确认团队习惯 |
+| `agent-engineering/multi-agent-coordination` | 并行任务、写路径隔离、handoff、review 复验 | 多 Agent 概念介绍 |
+| `agent-engineering/knowledge-governance` | draft/verified/proven、冲突、衰减、归档、团队同步 | 没有 evidence 的“最佳实践” |
+
+## 从外部来源提炼条目的流程
+
+```text
+1. 明确要解决的 Agent 决策问题。
+2. 搜索官方文档、开源项目实践或团队历史记录。
+3. 只提炼可执行判断，不搬运完整内容。
+4. 写成 100-300 字短条目。
+5. 加 source_references、适用阶段、不适用条件和 maturity=draft。
+6. 后续任务真正引用并验证后，再考虑升级 verified/proven。
+```
+
+示例条目：
+
+```markdown
+---
+id: GUIDELINE-TESTING-001
+type: guideline
+domain: quality-management
+subdomain: verification-engineering
+maturity: draft
+tags: [testing, verification]
+source_references:
+  - project: codex-herness
+    ref: docs/harness/regression-rules.md
+  - url: https://playwright.dev/docs/test-assertions
+applicable_phases: [implement, review, verify]
+last_referenced:
+validated_projects: []
+contradictions: []
+contributors:
+  - codex
+---
+
+# feature_impl 不能只用格式检查作为完成验证
+
+## Guidance
+
+实现任务必须至少运行一个能证明用户故事、接口行为或交付路径的验证命令。`git diff --check` 只能证明文本格式，不证明功能完成。
+
+## Not Applicable When
+
+任务明确是纯文档、索引或模板格式改动。
+
+## Evidence
+
+初始来源为 Harness 任务执行规则和测试工具文档，待后续项目 trace 验证。
+```
+
+## 必建目录
+
+```text
+team-wiki/
+  knowledge-catalog.md
+  .knowledge-config.yaml
+  log.md
+  quality-management/
+    catalog.md
+    requirements-quality/
+    verification-engineering/
+    review-gates/
+    risk-management/
+  software-engineering/
+    catalog.md
+    task-decomposition/
+    architecture-constraints/
+    integration-quality/
+    change-management/
+  agent-engineering/
+    catalog.md
+    workflow-control/
+    prompt-and-rule-governance/
+    multi-agent-coordination/
+    knowledge-governance/
+  project-profiles/
+    catalog.md
+  contributions/
+    pending/
+    conflicts/
+  archive/
+```
+
+## 初始全景目录
+
+`knowledge-catalog.md` 应先写清楚：
+
+- 本知识库服务哪些项目和团队。
+- 查询顺序：全景目录 -> 分类 catalog -> 条目。
+- 成熟度规则：`draft` / `verified` / `proven`。
+- 冲突规则：项目事实优先，团队知识冲突进入 `contributions/conflicts/`。
+- 写入规则：自动化只写 pending，不直接改主干知识。
+
+## 初始配置
+
+`.knowledge-config.yaml` 最小内容：
+
+```yaml
+schema_version: 1
+team:
+  name: codex-harness-team
+  default_role: reader
+roles:
+  maintainers: []
+  contributors: []
+sync:
+  accept_domains: [quality-management, software-engineering, agent-engineering]
+  require_maintainer_for_proven: true
+  allow_auto_pending: true
+conflicts:
+  on_content_conflict: stage_to_conflicts
+  on_maturity_conflict: keep_lower_and_mark_contradiction
+decay:
+  proven_months_without_reference: 12
+  verified_months_without_reference: 6
+```
+
+## 第一批种子内容
+
+### Requirements Quality
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| GUIDELINE-REQ-001 | guideline | P0/P1 需求必须有可测试验收标准 | draft | 防止 AI 凭感觉实现 |
+| GUIDELINE-REQ-002 | guideline | Requirement ID 必须能追溯到 UI/API/数据/测试 | draft | 支撑 Stage 1 Review |
+| PITFALL-REQ-001 | pitfall | 未收敛需求直接编码会造成 scope 漂移 | draft | AI 编程高频失败 |
+
+### Verification Engineering
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| GUIDELINE-VERIFY-001 | guideline | feature_impl 不能只用格式检查作为完成验证 | draft | 防止假完成 |
+| GUIDELINE-VERIFY-002 | guideline | 完成声明必须有 fresh evidence | draft | 防止编造完成 |
+| PITFALL-VERIFY-001 | pitfall | Release 阶段第一次补测试范围会掩盖需求缺口 | draft | Harness 阶段约束 |
+| PROCESS-VERIFY-001 | process | affected tests 选择流程 | draft | 支撑验证工程 |
+
+### Review Gates
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| PROCESS-REVIEW-001 | process | Stage 1 审产品、设计、计划和架构约束 | draft | 防止评审职责混杂 |
+| PROCESS-REVIEW-002 | process | Stage 2 审代码质量、测试、安全和回归风险 | draft | 防止只看需求不看实现 |
+| GUIDELINE-REVIEW-001 | guideline | Finding 必须包含 owner、evidence 和 repair queue | draft | 让修复可执行 |
+
+### Task Decomposition
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| GUIDELINE-TASK-001 | guideline | 单个 task 必须有 owned paths 和独立验证闭环 | draft | 防止大任务失控 |
+| GUIDELINE-TASK-002 | guideline | release 任务只刷新证据，不首次补范围 | draft | 保持阶段职责 |
+| PITFALL-TASK-001 | pitfall | 多 Agent 同时写同一路径会造成不可控冲突 | draft | 并行协作常见坑 |
+
+### Architecture Constraints
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| GUIDELINE-ARCH-001 | guideline | 每个实现任务应声明交付形态、公开入口和数据边界 | draft | 支撑通用架构约束包 |
+| GUIDELINE-ARCH-002 | guideline | 不适用的边界必须写 `not_applicable` 而不是留空 | draft | 防止 Agent 猜测 |
+| PITFALL-ARCH-001 | pitfall | 测试替身冒充声明交付路径会导致验收失真 | draft | 来自近期架构约束门禁需求 |
+
+### Agent Workflow Control
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| DECISION-AGENT-001 | decision | Driver-first 优先于聊天内手工维护任务状态 | draft | 当前 Harness 核心架构决策 |
+| GUIDELINE-AGENT-001 | guideline | 实现任务必须带 truth source、owned paths 和验证命令 | draft | 防止任务不可验证 |
+| PROCESS-AGENT-001 | process | BLOCKED 输出和人工介入协议 | draft | 防止伪继续 |
+
+### Prompt And Rule Governance
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| GUIDELINE-RULE-001 | guideline | AGENTS 只放入口硬约束，细节放深文档 | draft | 防止根规则膨胀 |
+| GUIDELINE-RULE-002 | guideline | 单次经验先进入知识库，不直接升级 prompt/template | draft | 控制规则污染 |
+
+### Knowledge Governance
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| PROCESS-KNOWLEDGE-001 | process | 知识条目从项目归档提升到团队库的流程 | draft | 防止直接把项目经验升全局规则 |
+| GUIDELINE-KNOWLEDGE-001 | guideline | 项目事实优先于外挂知识 | draft | 防止团队库误覆盖当前项目 truth source |
+| GUIDELINE-KNOWLEDGE-002 | guideline | draft 知识不能作为阻塞性 Review 依据 | draft | 控制误杀 |
+| PROCESS-KNOWLEDGE-002 | process | 团队知识冲突进入 pending/conflicts 并人工裁决 | draft | 解决多项目结论矛盾 |
+
+### Project Profiles
+
+| ID | 类型 | 标题 | 初始成熟度 | 为什么先建 |
+| --- | --- | --- | --- | --- |
+| MODEL-PROJECT-001 | model | 项目画像最小字段 | draft | 支持按项目过滤知识 |
+
+项目画像最小字段：
+
+```yaml
+project_slug:
+domains: []
+tech_stack: []
+delivery_shape:
+knowledge_sources:
+  project: docs/knowledge
+  team:
+validated_rules: []
+known_conflicts: []
+```
+
+## 条目模板
+
+```markdown
+---
+id: <TYPE-AREA-NNN>
+type: guideline
+domain: quality-management
+subdomain: verification-engineering
+maturity: draft
+tags: []
+applicable_phases: []
+source_references:
+  - project:
+    ref:
+last_referenced:
+validated_projects: []
+contradictions: []
+contributors:
+  - codex
+---
+
+# <title>
+
+## Context
+
+## Guidance
+
+## Not Applicable When
+
+## Evidence
+```
+
+## 不要首批加入的内容
+
+- 大段框架官方文档。用链接和摘要，不复制全文。
+- 未验证的个人偏好。
+- 只适用于单个项目的路径、命令和部署细节。
+- 没有替代方案的禁令。
+- 没有 source reference 的“最佳实践”。
+- 会泄露 token、cookie、私钥、客户数据或内部密钥的内容。
+
+## 初始验收标准
+
+第一版外挂总知识库达到以下状态即可开始试用：
+
+- `knowledge-catalog.md` 存在并说明查询顺序。
+- 每个一级目录都有 `catalog.md`。
+- 至少 10 条种子知识，全部有 frontmatter。
+- 所有种子条目默认为 `draft`，除非有明确 evidence。
+- `.knowledge-config.yaml` 存在。
+- `log.md` 存在，并记录初始化动作。
+- 项目侧 `.knowledge-sources.yml` 可以指向该仓库。

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

@@ -0,0 +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。

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

@@ -0,0 +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`
+
+## 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/*`: 历史经验和长期可复用知识