@pzy560117/codex-harness 0.1.2 → 0.1.4

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

@@ -1,34 +0,0 @@
-# 通用 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

@@ -1,296 +0,0 @@
-# 外挂总知识库初始内容
-
-外挂总知识库最初必须先设定目录、元数据和种子内容，否则后续会变成散乱文档堆。第一版不追求内容多，重点是覆盖 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

@@ -1,221 +0,0 @@
-# 外挂总知识库落地路线
-
-## 阶段 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 +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。
-- 完成声明能说明声明交付路径、测试替身和不适用边界。