feat(kb): add docs-first feature discovery to initialization

doc/architecture/SPEC/kb_service.md

@@ -1,6 +1,6 @@
 # kb_service/ —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-05 -->
 
 `知识服务核心：仓库配置、账本、outbox、CLI · refactor-status: new`
 
@@ -783,3 +783,64 @@ dry run 为旧快照建本地临时 baseline，再生成相同升级串与全量
 ## 自主进化接入
 
 自主进化开启时起草前捕获事件与知识快照；已采用制品通过隔离代理起草 typed operations，宿主沿用已有知识发布权限与门禁。进化实验只在内存应用，不写产品知识库。
+
+## 2026-10-05 通用功能发现：文档基线与源码扩展
+
+初始化保留三个大阶段：Skeleton 建骨架，Modules/Knowledge 铺广度，
+Deepen/Acceptance 做深度并验收。新的 `feature-discovery` 位于 skeleton 与 modules
+之间；它先依据项目文档发现能力，再遍历固定源码范围寻找文档未说明的能力。
+
+```mermaid
+flowchart TD
+  P[仓库配置：SHA、范围、语言、owner、预算与目标] --> S[Skeleton]
+  S --> D[文档功能发现]
+  D --> C[源码扩展发现]
+  P --> D
+  P --> C
+  C --> R[聚合与独立评审]
+  R --> F[目录 PR：审查合并后冻结]
+  F --> B[Modules / Knowledge]
+  P --> B
+  B --> A[Deepen / Acceptance]
+  P --> A
+```
+
+新初始化配置启用 `knowledge_lifecycle.init.feature_discovery_required: true`。
+使用[通用新仓库配置模板](../templates/kb-init-new-repository.yaml)，按实际仓库调整源码范围、
+排除规则与文档入口；模板不修改既有适配器，也不改变其发布权限。
+旧适配器不配置该字段时仍使用既有显式目录；一旦开始发现批次，后续阶段不能绕过
+尚未完成或未合并的目录 PR。已有仓库可运行：
+
+```bash
+infermatrix-copilot kb init REPO --stage feature-discovery --from-existing \
+  --pin FULL_SHA --dry-run --unlimited-subscription
+```
+
+`--dry-run` 保存目录和 PR 正文供审查；省略它时沿用 init 的发布权限与 PR 流程。
+订阅模式明确使用 Zcode GLM‑5.3 提取、Codex 独立评审，不使用 Claude Code。
+默认并发上限为 13，两轮按顺序运行，轮内共享线程池；Zcode 请求沿用共享排期。
+`KB_DISCOVERY_GENERATOR`、`KB_DISCOVERY_JUDGE`、`KB_DISCOVERY_CONCURRENCY`
+覆盖发现阶段配置；提取与评审必须属于不同模型家族。`--budget-usd` 与
+`--unlimited-subscription` 互斥。未报告实际费用时保持未知，记账值不当作发票费用。
+
+发现使用完整文件库存和分片，不把前 N 个文件、前 N 行当作全仓库。范围、排除规则、
+文档入口与功能分母按仓库配置；未知语言使用文本和入口线索，并保留未解析关系。
+没有文档不阻断源码轮，正式功能允许 `docs: []`。目录以外的疑似第一方代码列为
+范围扩展建议，不静默改变本轮覆盖分母。源码与测试只有文本证据，本流程不执行
+上游测试，也不因未找到测试而声称没有测试。
+
+现有功能 ID 与 owner 保留。候选可成为新增功能、实现补充、别名、子能力、共享组件、
+过期声明或未知；文档声明必须找到实现证据才能成为新增正式功能。每项最多三次
+自动修正，未知不影响其他项继续。新 owner 由 modules 建立导航，目录发现不生成
+占位知识页，也不调整验收门槛或发布权限。
+
+冻结结果继续使用适配器目录下的 `knowledge-coverage.yaml`。紧凑记录保存于
+`eval/feature-discovery/REPO-PIN12.json`，绑定源码 SHA、目录哈希、发现来源、独立评审
+和未知项。完整输入、流式输出、工具调用、配置和用量保存到 init 外部状态目录的
+原生追踪档案；Git 内只保留引用与摘要。后续阶段核对目录/报告哈希及源码版本。
+已完成的分片和评审可恢复；预算耗尽留下未处理任务时保存检查点，不能标为完成。
+
+报告分开呈现文档候选、源码新增、实现补充、重复/过期/未知、失败分片和未关联范围。
+只能称“声明库存已处理”，不能证明所有功能均已发现。新目录的深度分母为 `N × 7`；
+历史目录的认可率独立保留，不能直接混用。功能发现、知识认可、生产文件结构覆盖、
+测试覆盖和真实 PR 评审效果是不同指标。

doc/architecture/SPEC/playbooks/PLAYBOOKS.md

@@ -1,6 +1,6 @@
 # playbooks/*.yaml —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-05 -->
 
 `9 个文件 · 声明式编排数据 · refactor-status: ok`
 
@@ -59,8 +59,13 @@ success, steps[]`。
 知识服务的合并推进、发版巡检与快照激活；candidate 状态，由 `kb serve` 调度或 `kb run` 手动运行。
 
 ## kb-init（candidate）
-为一个仓库建知识库：单步 `knowledge.init`，每次运行一个阶段（skeleton → modules → knowledge（解释性知识）→ deepen + 生命周期开关 →
+为一个仓库建知识库：单步 `knowledge.init`，每次运行一个阶段（skeleton → feature-discovery（显式启用）→ modules → knowledge（解释性知识）→ deepen + 生命周期开关 →
 pr-history → harvest-calibration），每阶段一个由人合并的 PR。只由 `kb init REPO --stage S` 运行，不经 `kb serve`，不写服务账本。
+`feature-discovery` 先提取文档功能基线，再遍历固定源码与测试库存；独立评审后的目录 PR
+合并后冻结，下游核对目录哈希与源码版本。新初始化模板启用发现；旧仓库保持兼容。
+默认 GLM‑5.3 提取、Codex 独立评审，共享并发 13；支持 `from_existing`、
+`retry_unfinished`、`budget_usd` 或 `unlimited_subscription`。未知项不增加正式功能计数，
+原生追踪归档在 Git 外。详细契约见 [`../kb_service.md`](../kb_service.md)。
 `pr-history` 默认回溯 1000 个已合并上游 PR；可传 `pr_count` 和累计花费上限 `budget_usd`。
 每个非空知识升级一个 commit，汇成一个 draft PR，完整 Codex 审阅通过后才 ready。
 `knowledge` 可传 `from_existing` 从已合并索引与路由增补（保留已有阶段记录的门禁），

doc/architecture/SPEC/providers/codex.md

@@ -1,6 +1,6 @@
 # providers/codex.py —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-05 -->
 
 `LOC ~197 · harness transport（ChatGPT 订阅） · refactor-status: ok`
 
@@ -18,6 +18,9 @@ subscription_billing 只认可当前 CLI 明确报告 ChatGPT 登录、默认 op
 布尔状态不代表已测得零费用。
 配置读取、登录探测和实际执行使用同一 `sanitized_env()` 与有效 HOME；被过滤的
 `CODEX_HOME` 不得使检查与执行落在不同认证目录。
+`supports_native_events = True`；`complete(native_event_sink=...)` 将 `_run` 解析的全部
+JSONL 事件按原顺序封装为 `{"type": "native.codex.event", "payload": 原事件}` 后交给归档器。
+事件在进程退出或超时后批量转发，属于缓冲归档，不是运行期间的实时流；最终文本和用量解析保持一致。
 
 ## 不变量（**C1**、**C2**）
 - **控制手段是沙箱，不是工具列表。** Codex 无法关闭自己的原生 shell，所以容纳靠 OS 级的
@@ -27,8 +30,7 @@ subscription_billing 只认可当前 CLI 明确报告 ChatGPT 登录、默认 op
 - `_tool_activity` 是尽力而为的活动日志，**明确不是审计** —— 强制点是沙箱。
   不要让调用方把它当审计用。
 - `complete()` 在一个空的临时 cwd 里无工具运行，所以一次性调用**根本够不到仓库**。
-- `auth_gap()` 会报出 ChatGPT 登录缺口：这个后端**仅经离线测试**（开发机没有登录），
-  readiness 必须如实说出来，而不是暗示它已被验证。
+- `auth_gap()` 如实报告当前认证缺口；离线测试不代表调用环境已经通过原生预检。
 
 ## 边界 —— 不属于这里
 不发明沙箱策略（CLI 的 flag 就是契约）；不编造用量。
@@ -37,8 +39,8 @@ subscription_billing 只认可当前 CLI 明确报告 ChatGPT 登录、默认 op
 stdlib + `.base` + `..agent_loop.AgentOutcome` + `..llm` 的类型。
 
 ## 测试
-`test_provider_codex.py`（离线；实网路径**按设计未经验证** —— 见
-`doc/features/provider-registry.md` 里的状态说明）。
+`test_provider_codex.py` 使用离线假 CLI，覆盖完整事件归档、工具事件、最终回复及用量。
+实际环境的原生预检与运行结果由各批次报告记录。
 
 ## 重构备注
 **不要**把 `_tool_activity` "改进"成审计：`providers/audit.py` 的存在正是为了那些没有

doc/architecture/templates/kb-init-new-repository.yaml

@@ -0,0 +1,31 @@
+# Merge this snippet into a NEW repository adapter's manifest.yaml.
+# Retain the adapter's own knowledge_lifecycle mode, permissions and release policy.
+# Existing adapters opt in explicitly; this template does not migrate them.
+knowledge_lifecycle:
+  init:
+    feature_discovery_required: true
+    # Replace these roots with the repository's first-party production scope.
+    # "." includes root-level libraries, CLIs and multi-language monorepos.
+    source_roots: ["."]
+    exclude:
+      - "vendor/*"
+      - "third_party/*"
+      - "node_modules/*"
+      - "dist/*"
+      - "build/*"
+    # Add owner-maintained material wherever this repository stores it.
+    # An empty or unmatched documentation inventory still proceeds to source discovery.
+    doc_globs:
+      - "README*"
+      - "**/README*"
+      - "docs/**"
+      - "doc/**"
+      - "CONTRIBUTING*"
+    seeds: []
+    coverage_target: 0.85
+    budget_usd: 30.0
+
+# Discovery defaults: Zcode GLM-5.3 generation, independent Codex review, concurrency 13.
+# Override with KB_DISCOVERY_GENERATOR, KB_DISCOVERY_JUDGE, KB_DISCOVERY_CONCURRENCY.
+# --unlimited-subscription requires both subscription backends and replaces this
+# run's USD ceiling. Unreported invoice costs remain unknown.

eval/feature-discovery/README.md

@@ -0,0 +1,59 @@
+# 通用初始化功能发现：实现与试运行
+
+新增 `feature-discovery`，在 Skeleton 与 Breadth 之间执行“文档基线 → 源码扩展 → 聚合与独立评审 → 目录 PR”。正式发布后，后续阶段必须等待目录合并并核对源码版本、功能 ID、owner 和目录哈希。三个大阶段仍为 Skeleton、Breadth、Deepen / Acceptance。
+
+![初始化流程](visualizations/init-feature-discovery-workflow-cn.svg)
+
+## 通用性与兼容
+
+- 新适配器使用 [初始化模板](../../doc/architecture/templates/kb-init-new-repository.yaml)，显式启用发现；旧适配器默认保持既有流程。一旦启动发现，下游不能绕过未完成或未合并的目录。
+- 完整生产、测试、文档库存按固定 SHA 与扫描范围建立，复用于发现、modules 和基础知识。逐文件识别语言；未知语言使用文本线索并记录未解析关系。第三方与生成物按配置排除。
+- 文档轮读取正文；无文档继续源码轮。源码轮先探索未关联区域，再处理其余声明分片，不把前 N 个文件或行当作完整范围。
+- 正式功能与待审候选分别标记。跨层实现可以归并；文件、函数或页面不会自动成为独立功能。旧 ID 与 owner 不自动删除或改名；新 owner 请求由 modules 创建导航。
+- `docs: []` 合法。覆盖政策、权限与生命周期不随目录 PR 改动。新深度分母为冻结目录的 `N × 7`，历史统计保持独立。
+
+## 运行与恢复
+
+```bash
+infermatrix-copilot kb init REPO --stage feature-discovery --from-existing \
+  --pin FULL_SHA --dry-run --unlimited-subscription
+```
+
+去掉 `--dry-run` 使用原有发布权限与 PR 流程；合并后继续 modules 和 knowledge。
+默认 Zcode GLM‑5.3 提取、Codex `gpt-6.1-sol:medium` 独立评审，共享并发上限 13；
+`KB_DISCOVERY_GENERATOR`、`KB_DISCOVERY_JUDGE`、`KB_DISCOVERY_CONCURRENCY` 可覆盖。
+`--budget-usd` 与不限订阅模式互斥。未报告实际费用时保持未知。
+
+检查点绑定源码、范围、种子目录、索引版本、提示词与模型配置。成功分片、评审和待审修正稿可复用；预算中断不标为完成。竞争启动同一批次不会覆盖检查点。单项最多三次修正；通道故障保持未知，不重做已成功的提取。仅有文档的未知声明不通过重复改写变成实现证明。
+
+紧凑摘要写入 `eval/feature-discovery/`。完整输入、原生输出、工具事件、配置、用量和修正过程留在 Git 外。恢复时核验每个完成分片的原生归档，包括返回空候选的分片。Zcode 保存原生流式事件；Codex 保存 CLI 结束后按原顺序转发的事件。
+
+## JiuwenSwarm 试运行口径
+
+[原生试运行记录](jiuwenswarm-pilot-20261005.json) 固定上游 `f0a69728c96b5961d993449f1a901cbd2f4dac5b`，
+读取 `docs/zh/单机多实例运行.md` 与 `jiuwenswarm/instance_manager/status.py`，共 **1 篇文档、1 个生产文件、0 个测试文件**。
+这是明确的小范围增量试运行，未发布正式目录，也未执行上游测试。
+
+文档轮与源码轮聚合出 **6 个候选**。原生调用为 **3 次 GLM‑5.3 提取/修正、2 次 Codex 评审**；
+GLM 记录的实际模型为 `GLM-5.3`，Codex CLI 未报告 served model，故该字段保持未知。
+原始评审出现“候选关联自身”的目录边界问题：目录校验只接纳 **1 项实现补充**，其余 **5 项保持未知**，其中 **2 项仅有文档声明**。
+原有 **79 个功能和 553 维度历史分母保持不变**。
+
+这一结果促成了两项修复：提示词区分正式功能与待审候选；无效补充/别名目标进入单项修正。
+[新的独立复核](jiuwenswarm-recheck-20261005.json) 使用独立批次复用真实提取记录，重审关系与边界：**4 个候选获支持并关联到既有 `instances` 功能（3 项实现补充、1 项子能力），2 项仅有文档的声明保持未知，0 项新增正式功能**。
+新增调用仅为 **1 次 Codex 评审**。它不是原批次的无记录续跑，也不冒称重新完成了提取。
+
+[Codex 事件预检](codex-trace-preflight-20261005.json) 验证新事件归档能原生运行：4 个事件已归档且可回放。
+完整外部归档、检查点、提示词和运行代码的路径与 SHA256 见各 JSON；费用均未报告。
+早期范围过大的试运行与评审通道空结果记录保留在外部档案中，未当作成功结果。
+
+## 验证与限制
+
+测试覆盖无文档、纯库、多语言与未知语言、嵌套测试、晚于旧截断位置的内容、跨层合并、别名、新 owner、旧目录兼容、范围漂移、模型独立性、中断恢复、原生归档损坏与失败分片。
+
+本地全量回归：**3429 项通过、18 项跳过、0 失败**（3447 项）；随后最终边界、恢复与事件归档 **95 项针对性回归通过**。
+最终代码复核独立评审原生结论与输入候选的绑定通过，审计记录保存在独立复核外部目录的 `approval-audit.json`。
+文档链接、引用、SPEC 严格检查及知识目录两个校验器通过。最终提交由 CI 复核全部测试。
+纯库与多语言通用性由仓库夹具测试验证，未据此声称这些仓库做过原生模型实测。
+
+处理完声明库存不等于发现了所有功能。该试运行不提供全仓功能覆盖率、测试覆盖率或 PR 评审准确率/速度收益；它验证发现、边界校验、独立评审及归档链路。

eval/feature-discovery/codex-trace-preflight-20261005.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": 1,
+  "kind": "codex-native-event-preflight",
+  "trace_id": "1791194128700-30fad72a4018",
+  "reply_sha256": "4062edaf750fb8074e7e83e0c9028c94e32468a8b6f1614774328ef045150f93",
+  "requested": "codex:gpt-6.1-sol:medium",
+  "served_model": null,
+  "usage": {
+    "input_tokens": 14549,
+    "output_tokens": 9,
+    "cache_read_input_tokens": 0,
+    "cache_creation_input_tokens": 0
+  },
+  "seconds": 9.591010093688965,
+  "actual_cost_usd": null,
+  "native_event_count": 4,
+  "native_events_sha256": "sha256:b9b03b5895d68812487bf71fb5b0414b9ea671b4ea519b08be7e5ebaf772bbb0",
+  "archive": "/data/zhoutaichang/copilot/.feature-discovery-codex-trace-preflight-20261005"
+}