@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,33 +0,0 @@
-# App Knowledge Catalog
-
-本目录保存移动端和全平台 App 生产可上线相关的外挂知识候选。Codex 会话应先读本 catalog，再判断是否需要读取完整规范文件；不要把完整长文档作为默认上下文。
-
-## 查询顺序
-
-1. 当前任务涉及移动端 App、H5 / WebView、Hybrid、小程序、上架审核、支付、隐私、安全、灰度、回滚、生产发布或移动端 QA 时，先读本文件。
-2. 需要完整 Release Gate、测试矩阵或行业案例时，再读取对应规范文件。
-3. 如果当前项目已有 PRD、架构约束、测试矩阵或合规规则，以项目事实为准；本目录只作为补充检查和 checklist 来源。
-
-## 条目索引
-
-| ID | Type | Maturity | Title | Tags | Path |
-| --- | --- | --- | --- | --- | --- |
-| FRAMEWORK-APP-READINESS-001 | framework | draft | Mobile App Production Readiness Framework：移动端全平台生产可上线规范与宠物商城行业案例 | mobile-app, release-gate, qa, privacy, security, app-store, ecommerce, pet-commerce | `docs/external-knowledge/app/Mobile_App_Production_Readiness_Framework_移动端全平台生产可上线规范.md` |
-
-## 适用阶段
-
-| 阶段 | 推荐用途 |
-| --- | --- |
-| analysis | 识别平台范围、隐私合规、商店审核、支付、行业高风险边界 |
-| design | 补齐 App 生命周期、权限、离线弱网、灰度回滚、可观测性和后台治理要求 |
-| plan | 拆分 iOS、Android、H5 / WebView、小程序、服务端、后台、QA、安全和合规任务 |
-| implement | 检查生产包、SDK、权限、WebView、Deep Link、支付、数据同步等实现边界 |
-| review | 作为 Stage Review 的移动端生产可上线 checklist，但 `draft` 内容不能单独作为阻塞依据 |
-| verify | 生成 Release Gate、真机矩阵、支付/退款、隐私、安全、灰度和回滚证据清单 |
-
-## 使用边界
-
-- 本目录内容初始为 `draft`，只能作为启发和检查清单，不能覆盖当前项目 truth source。
-- 涉及法律、医疗、兽药、活体交易、跨境数据、儿童、金融等高风险事项时，必须由项目法务或合规负责人确认。
-- 宠物商城内容是行业案例，不代表所有电商 App 的默认要求；非宠物行业只复用通用移动端框架部分。
-- 后续如果拆分为独立条目，应保留本 catalog 作为长文档入口，并把可验证规则提炼成短条目。

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

@@ -1,358 +0,0 @@
-# AI 软件工程质量知识库项目架构
-
-本文把外挂总知识库定义为一个完整项目，而不是一组散落 Markdown。项目暂名 `team-wiki`，定位是面向 AI 编程的质量管理与软件工程知识系统。
-
-## 1. 项目定位
-
-`team-wiki` 不是泛技术百科，也不是简单文档站。它服务于 Codex、reviewer、test-runner、planner 和人类维护者，目标是解决 AI 编程中的质量痛点：
-
-- 需求没收敛就开始编码。
-- 任务拆分过大、owned paths 不清。
-- AI 编造完成状态或绕过验证。
-- 测试替身、demo、mock 冒充声明交付路径。
-- review 只看代码风格，不看需求、架构和证据。
-- release 阶段才第一次补测试范围。
-- 多 Agent 并行写冲突。
-- 经验无法复用，每个项目重复踩坑。
-- 规则、prompt、模板越写越重，缺少升级和衰减治理。
-
-第一版核心知识域必须围绕质量管理和软件工程，不优先建设 React、Django、Docker 这类技术栈百科。技术栈知识只有在它直接影响质量门禁、验证或工程治理时才进入第一版。
-
-允许按领域增加独立扩展包，但扩展包必须服务于生产准入、验证、合规、发布治理或行业风险控制。例如 `app/` 领域扩展用于移动端和全平台 App 的生产可上线检查，不作为泛移动开发教程。
-
-## 2. 产品边界
-
-### 用户角色
-
-| 角色 | 需求 |
-| --- | --- |
-| Codex 实现会话 | 在实现前读取少量高相关质量规则和历史坑 |
-| Planner / Architect | 拆任务、定义架构约束、设计验证闭环 |
-| Stage Reviewer | 根据成熟知识检查需求、架构、验证和风险 |
-| Test Runner | 选择 affected tests、识别假验证和环境坑 |
-| Maintainer | 审批知识晋级、冲突裁决、规则升级 |
-| 新项目接入者 | 快速获得 AI 编程质量基线和项目画像模板 |
-
-### 非目标
-
-- 不做完整技术百科。
-- 不复制 GitHub 项目的 Wiki、README 或代码。
-- 不替代当前项目 PRD、架构约束、测试矩阵。
-- 不让外部知识库成为 driver 的硬依赖。
-- 不让 Codex 静默把 `draft` 知识升级为 `proven`。
-
-## 3. 系统模块
-
-```text
-team-wiki/
-  content/             # 知识源文件，Git + Markdown
-  catalogs/            # 汇总索引和 Agent 查询入口
-  schemas/             # frontmatter 和配置 schema
-  scripts/             # lint、resolve、export、index
-  contributions/       # Codex 或项目导出的 pending/conflict 候选
-  reports/             # lint、sync、promotion、decay 报告
-  docs/                # 使用说明和治理协议
-```
-
-模块职责：
-
-| 模块 | 职责 |
-| --- | --- |
-| Content Store | 保存知识条目，是唯一事实源 |
-| Catalog Index | 给人和 Agent 提供低成本查询入口 |
-| Source Resolver | 读取项目 `.knowledge-sources.yml`，解析外挂知识路径 |
-| Lint Engine | 检查 frontmatter、catalog、重复、冲突、成熟度越权 |
-| Sync Engine | 从项目 `docs/knowledge/` 导出团队候选 |
-| Promotion Workflow | 维护 draft/verified/proven 晋级和衰减 |
-| Retrieval Adapter | 第一阶段用 catalog；后续可接 RAG，但 RAG 不做事实源 |
-
-## 4. 知识域架构
-
-第一版目录按 AI 编程质量问题组织：
-
-```text
-team-wiki/
-  README.md
-  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/
-  app/
-    catalog.md
-    production-readiness/
-  project-profiles/
-    catalog.md
-  contributions/
-    pending/
-    conflicts/
-  reports/
-  archive/
-  schemas/
-  scripts/
-```
-
-### 质量管理域
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `requirements-quality/` | 需求可测试性、验收标准、Requirement ID、追溯矩阵 |
-| `verification-engineering/` | affected tests、fresh evidence、失败态证据、假验证 |
-| `review-gates/` | Stage 1/2 分工、finding 格式、repair queue |
-| `risk-management/` | 外部依赖、安全、权限、数据、部署风险 |
-
-### 软件工程域
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `task-decomposition/` | task.json 拆分、owned paths、dependencies、单任务闭环 |
-| `architecture-constraints/` | 交付形态、公开入口、数据边界、异步边界、禁止伪实现 |
-| `integration-quality/` | contract first、真实依赖、mock 切真实接口、联调证据 |
-| `change-management/` | 变更范围、回归、兼容性、迁移和发布收口 |
-
-### Agent 工程域
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `workflow-control/` | driver-first、truth source、BLOCKED 协议、不伪造状态 |
-| `prompt-and-rule-governance/` | AGENTS/prompt/template 的写入边界和升级条件 |
-| `multi-agent-coordination/` | 并行任务、写路径隔离、handoff、review 复验 |
-| `knowledge-governance/` | draft/verified/proven、冲突、衰减、归档、团队同步 |
-
-### App 生产可上线域
-
-`app/` 是领域扩展包，不属于第一版核心三大域的替代项。它面向移动端和全平台 App 的生产发布质量，只有在任务涉及 App、H5 / WebView、Hybrid、小程序、商店审核、支付、隐私、安全、灰度、回滚、移动端 QA 或行业专项时才按需读取。
-
-| 子域 | 解决的问题 |
-| --- | --- |
-| `production-readiness/` | iOS、Android、H5 / WebView、小程序、后台、服务端、支付、隐私、安全、商店审核、灰度、回滚和 Release Gate |
-| `industry-cases/` | 电商、宠物商城等行业案例、P0 测试用例、高风险边界和行业专项 Release Gate |
-
-## 5. 数据模型
-
-### 知识条目
-
-```yaml
-id: GUIDELINE-VERIFY-001
-type: guideline
-domain: quality-management
-subdomain: verification-engineering
-maturity: draft
-tags: [verification, ai-coding, evidence]
-applicable_phases: [plan, implement, review, verify]
-source_references:
-  - project: codex-herness
-    ref: docs/harness/regression-rules.md
-validated_projects: []
-last_referenced:
-contradictions: []
-contributors:
-  - codex
-owner:
-not_applicable_when: []
-```
-
-正文必须包含：
-
-```markdown
-# 标题
-
-## Problem
-
-## Guidance
-
-## Not Applicable When
-
-## Evidence
-```
-
-### 项目画像
-
-```yaml
-project_slug:
-domains: []
-tech_stack: []
-delivery_shape:
-quality_profile:
-  critical_paths: []
-  required_gates: []
-  verification_baseline: []
-knowledge_sources:
-  project: docs/knowledge
-  team:
-validated_rules: []
-known_conflicts: []
-```
-
-项目画像用于过滤团队知识，避免把不相关技术栈或业务域注入到当前任务。
-
-### 贡献候选
-
-```yaml
-candidate_id:
-source_project:
-source_entry:
-target_domain:
-target_subdomain:
-suggested_action: add | merge | promote | conflict | decay
-evidence:
-review_required: true
-```
-
-候选只进入 `contributions/pending/` 或 `contributions/conflicts/`，不直接改主干条目。
-
-## 6. 来源策略
-
-`team-wiki` 不是复制别人的 Wiki，而是把可授权、可追溯、可验证的来源提炼成团队自己的短条目。
-
-| 来源 | 优先级 | 用法 | 初始成熟度 |
-| --- | --- | --- | --- |
-| 团队真实项目经验 | 最高 | 从 trace、review、失败记录、事故复盘和测试缺口提炼 | `draft`，复用验证后升级 |
-| 官方文档和标准 | 高 | 摘要规则、链接来源、写明版本或适用范围 | `draft` 或 `verified` |
-| 优秀开源项目实践 | 中 | 借鉴目录、流程、测试、CI、ADR 和治理模式，不复制原文 | `draft` |
-| 公开文章和案例 | 中低 | 作为启发和候选，不作为强约束 | `draft` |
-| 人工访谈和团队约定 | 高 | 记录来源人、日期、适用项目和验证计划 | `draft` |
-
-禁止事项：
-
-- 不直接复制 GitHub 项目的 README、Wiki、文档或代码作为知识条目。
-- 不复制许可证不清晰的大段文本。
-- 不把别人项目的具体路径、命令、部署和业务规则当成通用规则。
-- 不把博客观点直接写成 `proven`。
-- 不收录 token、cookie、私钥、客户数据、内部密钥或真实敏感配置。
-
-## 7. 成熟度和治理
-
-| 成熟度 | 定义 | 使用边界 |
-| --- | --- | --- |
-| `draft` | 单项目、单任务或人工导入候选 | 只能启发分析，不能作为阻塞性 review 依据 |
-| `verified` | 至少一个真实任务引用并通过验证 | 可作为 reviewer 辅助依据 |
-| `proven` | 至少两个不同任务或项目验证，或 maintainer 审批 | 可提升为规则、模板、prompt 或默认检查 |
-
-规则：
-
-- `draft -> verified` 需要真实任务引用和验证证据。
-- `verified -> proven` 需要两个不同任务或项目证据，或 maintainer 明确审批。
-- 冲突条目保留较低成熟度，并进入 `contributions/conflicts/`。
-- 长期未引用条目进入 decay candidate，不自动删除。
-- 只有 `proven` 或用户明确要求，才考虑升级到 `AGENTS.md`、prompt、模板或脚本。
-
-## 8. 查询和接入
-
-项目根目录使用 `.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]
-```
-
-Codex 查询顺序：
-
-1. 当前项目 truth source：PRD、架构约束、测试矩阵、项目 `docs/knowledge/`。
-2. `.knowledge-sources.yml` 中可用的团队 catalog。
-3. 按 domain、subdomain、tags、phase、maturity 过滤。
-4. 读取少量相关条目。
-5. 最终报告列出 `knowledge_references`，包括 `source=project|team`。
-
-外挂知识不可用时只降级 warning，不能阻塞本地实现验证。
-
-长文档接入规则：
-
-- catalog 是默认入口，完整长文档不是默认上下文。
-- 长文档必须通过 catalog 暴露摘要、适用阶段、使用边界和路径。
-- 只有任务显式命中相关平台、行业、发布或验证风险时，才读取长文档相关章节。
-- 如果长文档中的 `draft` 建议与项目 truth source 冲突，以项目事实为准，并输出 conflict candidate。
-
-## 9. 脚本和接口
-
-第一版至少需要：
-
-```text
-scripts/
-  resolve-sources.ps1        # 解析 .knowledge-sources.yml
-  lint-knowledge.ps1         # 检查条目和 catalog
-  export-team-candidates.ps1 # 从项目知识导出 pending/conflict
-  build-agent-index.ps1      # 生成给 Agent 快速读取的摘要索引
-```
-
-脚本边界：
-
-- 不自动删除知识。
-- 不静默提升为 `proven`。
-- 不修改外部仓库主干，只写 pending/conflicts/report。
-- 外挂库不可用时 exit 0 + warning，除非用户显式要求强制同步。
-
-## 10. 质量门禁
-
-项目自身必须有质量门禁：
-
-| 门禁 | 命令或检查 |
-| --- | --- |
-| Markdown 格式 | `git diff --check` |
-| Frontmatter 完整 | `lint-knowledge.ps1` |
-| Catalog 一致 | `lint-knowledge.ps1` |
-| 敏感信息扫描 | 禁止 token、cookie、私钥、客户数据 |
-| 成熟度越权 | proven 必须有多项目证据或审批 |
-| 冲突检查 | 相反指导进入 conflicts |
-
-## 11. 与 RAG 的关系
-
-第一阶段不需要向量库。满足以下条件再接 RAG：
-
-- 条目超过 300 条。
-- catalog-first 检索已经不足。
-- frontmatter、chunk、权限和引用格式稳定。
-
-RAG 只做召回层。事实来源仍是 Git 中的 Markdown 条目，最终引用必须指向 Markdown 文件。
-
-## 12. MVP 范围
-
-第一版 MVP 只做：
-
-1. `team-wiki` 仓库骨架。
-2. 三大知识域：`quality-management`、`software-engineering`、`agent-engineering`。
-3. 10-20 条 `draft` 种子知识。
-4. `.knowledge-config.yaml` 和 `knowledge-catalog.md`。
-5. `lint-knowledge.ps1` 和 `resolve-sources.ps1`。
-6. 项目侧 `.knowledge-sources.yml` 示例。
-7. Codex prompt 查询协议更新。
-
-不做：
-
-- Web UI。
-- 向量库。
-- 自动写团队知识主干。
-- 技术栈百科。
-- 自动升级 `proven`。