Add portable knowledge onboarding and autonomous feature discovery

doc/architecture/SPEC/app/run_service.md

@@ -1,13 +1,20 @@
 # app/run_service.py —— 规范
 
-<!-- verified-against: 2026-09-30 -->
+<!-- verified-against: 2026-10-06 -->
 
 `RunService` is the durable application boundary shared by the embedded
 Strict SDK and MCP transport. It owns policy-checked reserve/start, a queue
 drained by `STRICT_MAX_WORKERS` workers (default 1), isolated child launch, startup/orphan reconciliation,
 readiness, bounded status/result polling, and repository-scoped knowledge
 reads. Construction and polling require no CLI or MCP module import.
 
+Knowledge reads resolve repository slices from the same frozen view's registry,
+with legacy adapters retained as fallback. Search/read always pass the view's
+manifest verifier. Child launch forwards the host-only
+`ALLOWED_KNOWLEDGE_REPOSITORIES`; tool input cannot grant cross-repository access.
+Strict adaptive document tools share the run's `KnowledgeContextService` ledger;
+legacy standalone document endpoints retain their per-call read windows.
+
 Reservation and run ID containment go directly through `RunReservation`,
 not the workflow `Copilot` facade. `Copilot` remains for playbook readiness
 and workflow execution; it does not mediate the service's reserve or poll

doc/architecture/SPEC/config.md

@@ -1,6 +1,6 @@
 # config.py —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-06 -->
 
 `LOC ~658 · 配置 · refactor-status: oversized`
 
@@ -26,6 +26,11 @@ worker 数 `strict_max_workers`（`STRICT_MAX_WORKERS`，默认 1，启动时校
 以带标记的 JSON 评论贴到该锁定的 mailbox issue，供另一台主机上的 reviewbot 摄取）。
 
 ## 公开契约
+
+`allowed_knowledge_repositories`（`ALLOWED_KNOWLEDGE_REPOSITORIES`，默认空 tuple）是
+运行主机授权读取的跨仓库 ID。它不进入模型工具的权限参数；授权仍须与固定快照中的
+confirmed 依赖及源码/目录 pin 一同验证，空配置只允许当前仓库。
+
 带全部可调项的 `Settings`；`reviewer` / `intent`（回退到 `agent_model`）；
 `repo_path(name)`；`model_for(mode)`；`tier_target(role)` → `ResolvedTarget`；
 `expansion_env()`；`knowledge_runtime_repos`；`allowed_repo_roots`

doc/architecture/SPEC/direct_routing.md

@@ -1,13 +1,13 @@
 # direct_routing.py —— 规范
 
-<!-- verified-against: 2026-10-02 -->
+<!-- verified-against: 2026-10-06 -->
 
 `LOC ~880 · Direct 模式完整策略包与仓库中立的知识路由 · refactor-status: stable`
 
 ## 职责
 Direct 模式的知识路由**机制**。模块中不出现任何被服务仓库的名字：每个仓库的
-owner/model 路由表是知识数据 `knowledge/repos/<repo>/_routes.yaml`，仓库别名
-来自 `adapters/<repo>/manifest.yaml` 的 `repo.full_name`/`repo.aliases`。
+owner/model 路由表是知识数据 `knowledge/repos/<repo>/_routes.yaml`，仓库身份和别名
+优先来自同一固定视图的 `_repositories.yaml`，旧 adapter 别名保持兼容。
 公开面由 `contract.py` 再导出。
 
 ## 公开契约
@@ -39,7 +39,9 @@ Direct policy bundle）、`direct_knowledge_routes`、
   为模块级 `__getattr__` 惰性别名。
 - **路由选择按数据而非仓库名**：仓库有非空 `_routes.yaml` → title/body owner
   路由 + 模型路由 + scope fallback；否则有 adapter → changed-file 路由；否则
-  `unsupported_exact_router`。`_routes.yaml` 引用的页面不存在时 fail-closed。
+  `unsupported_exact_router`。已注册但未生成 owner routes 的仓库返回显式
+  `description_unrouted`，仍可检索自己的说明知识；不得借用其他仓库路由。
+  `_routes.yaml` 引用的页面不存在时 fail-closed。
 - `repo` 必填：空值抛 `ValueError`，不再默认某个仓库；形似路径的仓库名直接
   视为不支持。
 - **changed files 校验选择、绝不静默替换选择**：title/body 选 owner，
@@ -71,7 +73,9 @@ stdlib + PyYAML + `.adapters`（AdapterError / AdapterRegistry / RepoAdapter）+
 ## 扩展点
 新 owner 路由/模型规则 → 改对应仓库的 `_routes.yaml`（schema_version 1：
 `owners[{owner, path, signals, scope_prefixes}]`、可选 `models{dir, page}`）；
-新仓库 → 提供 adapter 与 `_routes.yaml`，不改 `src/`。
+新仓库 → 提供固定视图 registry 与 `_routes.yaml`，不要求打包 adapter、不改 `src/`。
+已有 adapter 仓库继续兼容。自适应 SDK 通过统一会话对本模块选出的规则/导航再计量；
+旧 bundle 的 6,000 字符相关背景预算保持不变。
 
 ## 测试
 `test_knowledge_view_routing.py`（150 个真实 vllm-omni PR 的黄金路由输出、

doc/architecture/SPEC/engine/agent_runtime.md

@@ -1,11 +1,18 @@
 # engine/agent_runtime/ —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-06 -->
 
 `LOC ~1690（7 个文件） · 引擎（受治理的 agent 运行时） · refactor-status: ok`
 
 ## 职责
 
+含 `_repositories.yaml` 的固定快照默认采用 `knowledge_context_profile="adaptive"`；
+旧快照默认 legacy，也可显式选择。`doc_search` / `doc_read` / `doc_related`、规则与
+`doc_context_briefing` 共用 run 私有累计会话，`doc_context_expand` 必须给原因且保留
+源码/输出留白。实际注入正文和哈希写 trace，runner直接注入已围栏的 `model_content`。
+跨仓库 target 只选择已确认依赖，授权由 Settings 固定传入；模型工具不能授予权限。
+
+
 开启 `profile_briefing_enabled` 且证据包含 `pr_diff` 时，runner 使用既有 diff parser 提取
 路径，通过 `doc_related` 在首个模型调用前注入同一有界知识背景。内容放入 untrusted
 围栏并转义标签；`review_knowledge_context` 记录命中页面、状态和正文长度。

doc/architecture/SPEC/kb_service.md

@@ -5,6 +5,16 @@
 `知识服务核心：仓库配置、账本、outbox、CLI · refactor-status: new`
 
 ## 职责
+- 通用接入：`git_source` 固定任意 Git 来源，`repo_spec` 保存经明确接受的范围；
+  `portable_init` 创建本地受审工作区，`portable_commands` 提供 onboard、register、
+  目录接受、发布和增量批次准备，不伪造已合并 PR。见 [通用知识库流程](../portable-kb.md)。
+- 功能发现：文档轮、源码轮、独立评审、最多两轮残留补查；共享完整库存和入口/契约单元，
+  单项最多三次修正，失败保持未知。`evidence_bundle` 将固定哈希行段传给后续阶段。
+- 存储与接受：`knowledge_store` 单一主存储加只读镜像；`portable_publication` 区分 foundation
+  与 final，默认只激活真实最终回执，显式 partial 仍为未完成。最终复核完整生产库存、
+  七维分别 >90%、每功能认可和 ≥85% 结构覆盖，原生认可由 `native_depth_audit` 重放。
+- `source_links` 为 GitHub、GitLab 和本地 `repo://` 源码生成固定版本引用；原 GitHub 引用
+  与历史认可正文保持一致。通用知识 pin 支持 SHA‑1/SHA‑256。
 - `config`：解析 adapter `knowledge_lifecycle`（未知键、非法模式/触发器、缺失审计插件、
   知识目录与 adapter 不一致、私有上游配 `auto_merge`、`auto_merge` 无校准集均抛
   `LifecycleConfigError`）；`load_registry` 返回按仓库名的注册表，`general` 由服务配置。

doc/architecture/SPEC/knowledge_context.md

@@ -0,0 +1,45 @@
+# knowledge_context.py —— 规范
+
+<!-- verified-against: 2026-10-06 -->
+
+## 职责与公开契约
+
+`KnowledgeContextService` 是 SDK、MCP 与 Strict 共用的、固定快照的知识上下文服务。
+`ContextBudget` 声明模型窗口与留白；`ContextError` 拒绝身份、权限或预算不一致。
+`open_session` / `status` / `expand` 管理会话；`related` / `search` / `read` / `inject`
+返回同一累计预算下的实际正文和引用。服务不调用模型、不改知识页、不宣称评审准确率。
+
+## 身份与权限
+
+会话身份绑定快照树哈希、仓库 ID、知识切片、源码 pin、目录和政策哈希、PR 源码 pin、
+review ID、计量器及预算配置。已验证快照每次读取复核 manifest；开发目录绑定真实文件
+内容摘要。恢复复用固定根，不能悄悄切到当前 active。来源 pin 支持完整 SHA-1 / SHA-256。
+
+仓库从固定视图的 `_repositories.yaml` 解析，旧目录只保留精确切片兼容，未知版本不猜测。
+跨仓库读取同时要求主机 `allowed_repositories` 授权与当前仓库中 `status: confirmed`
+的依赖；目标源码和目录哈希必须匹配。工具参数只能选择目标，不能授予权限；所有目标
+共享同一个累计预算。
+
+## 预算与正文
+
+默认初始 24,000、最高 64,000；模型上下文默认配置 131,072，源码留白 32,000、输出
+留白 8,192，还可预留其他 prompt。可用上限取知识上限和模型剩余窗口的较小值。
+扩大必须给出原因，不能占用留白。这些是主机配置，不能冒称探测到 served model 窗口。
+
+默认以 UTF-8 字节数作保守计量上界，`token_accounting` 明示此单位；主机可传稳定 ID
+的 tokenizer。`actual_provider_usage` 保持 unknown。计量包括正文、来源字段、JSON
+转义与 untrusted 围栏。仅 `model_content` 用于注入；`documents` 是不带额外正文的引用。
+片段截断清空完整已注入维度及对应 basis/mode/validation 标签；可用维度仍可补读。
+
+SQLite 运行账本必须位于知识树之外。事务串行记账，精确来源单元去重，重复请求幂等；
+扩大后允许继续未交付片段。缓存命中复核请求收据、正文摘要、计量和源文件；这属于完整性
+检查，不是针对可任意改写整个主机账本的签名。搜索与阅读重叠片段不保证全局语义去重。
+
+## 接入与验证
+
+新版 SDK 显式 `plan_adaptive` / 会话接口使用本服务；旧 `plan` 保留两页、6,000 字符契约。
+MCP 暴露同一 open/read/search/related/expand；Strict 在注册表快照默认 adaptive，旧树
+默认 legacy。规则与 briefing 经 `inject`，只接收真实文档 ID，不接收任意宿主散文。
+
+`test_knowledge_context.py`、`test_knowledge_retrieval.py` 验证累计预算、并发、恢复、
+留白、跨仓库权限、缓存篡改、实际注入标签以及 SDK/Strict 的固定快照接入。

doc/architecture/SPEC/knowledge_docs.md

@@ -1,6 +1,6 @@
 # knowledge_docs.py —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-06 -->
 
 `LOC ~280 · 供 Direct 与 Agent 共用的只读知识检索 · refactor-status: ok`
 
@@ -33,7 +33,8 @@ stdlib 与 `knowledge_service.lifecycle` 的页面/完整深读正文解析；
 结构化接口卡不进入背景。确定性优先级为固定来源路径、生产入口、源码 glob，再结合
 功能 ID/标题和正文词命中；相同 feature 去重，完整深读优先于基础功能页。
 最多返回两页、每页 3,000 字符、总计 6,000 字符；优先完整 facet，超长单 facet 仍提供
-截断片段并标 `more_available`。返回来源 pin、命中路径、已有/缺失 facet，不验证 PR head。
+截断片段并标 `partial` 与 `more_available`，不把截断 facet 列入 `included_facets`。
+返回来源 pin、命中路径、已有/缺失 facet，不验证 PR head。
 `available_facets` 表示页内可用维度，`included_facets` 表示本次正文实际注入的维度；
 `not_injected_facets` 是已有但因预算未注入的维度，调用方可用原有有界读取补读。
 `facet_basis` 与 `included_facet_basis` 分别对应已有及已注入维度的认可依据。
@@ -59,3 +60,12 @@ stdlib 与 `knowledge_service.lifecycle` 的页面/完整深读正文解析；
 
 ## 2026-09-28 退役规则不再提供
 `read`/`search` 经 `visible_text` 去掉退役规则后再返回。
+
+## 自适应调用边界（2026-10-06）
+
+旧默认仍是两页、6,000 字符。`related` 允许显式覆盖 `max_documents`、
+`max_page_chars`、`max_content_chars` 与 `max_changed_files`；自适应服务可取消改变文件
+列表的前缀限制。可选上限是 100 页、每页 65,536 字符、总 262,144 字符，最终实际交付
+仍由 `KnowledgeContextService` 累计预算裁剪。这些是字符限制，不是模型实际 token 用量。
+纯解析缓存按原文内容寻址，所有命中仍先验证固定快照的真实字节；不缓存路径读取以绕过
+完整性检查。此读取器没有累计补读账本；累计预算由显式会话服务负责。

doc/architecture/SPEC/knowledge_service.md

@@ -1,6 +1,10 @@
 # knowledge_service/ — provider curation components
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-06 -->
+
+Pinned source identities and depth markers accept full SHA-1 or SHA-256 Git
+commits. Evidence bodies, stored hashes and native approval semantics remain
+unchanged; accepting a wider object identity never renews an old approval.
 
 The provider owns knowledge curation beneath the public SDK v1 facade.
 `KnowledgeCurator` composes four domain components over one explicit work

doc/architecture/SPEC/knowledge_service/lifecycle.md

@@ -1,6 +1,8 @@
 # knowledge_service/lifecycle.py —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-06 -->
+
+深度区块的固定源码身份支持完整 SHA-1 或 SHA-256；旧区块正文、哈希及证明语义保持不变。
 
 深度验证入口缺失证书的当前检测器为 `static-test-association-v2`；解析、证书工厂和
 检索形状校验共用 `DEPTH_ABSENCE_DETECTOR`，算法升级不复用旧检测器身份。

doc/architecture/SPEC/knowledge_service/pinned_claims.md

@@ -1,14 +1,14 @@
 # knowledge_service/pinned_claims.py —— 规范
 
-<!-- verified-against: 2026-09-30 -->
+<!-- verified-against: 2026-10-06 -->
 
 `LOC ~200 · 在钉住的上游 SHA 上核验规则声明与代码证据（kb init §9.1） · refactor-status: new`
 
 ## 职责
 - `PinnedObserver(repo_dir, repository, pin, pull=)`：在本地 git 仓库（bare 或非 bare）上实现
   `facts.Observer`，`head()` 固定返回钉住的 SHA；`top_level` / `path_exists` / `file_text` 读 git
   对象，`pull(n)` 默认走 `gh api repos/{repo}/pulls/{n}`（可注入；任何查询失败——没有 `gh`、网络错误、非对象回答——都归一为 `FactsError`，原有的 `FactsError` 原样抛出）。另加协议之外的
-  `is_ancestor(sha)`：`sha` 是钉点或其祖先（非 40 位 SHA、镜像中不存在的对象、非 commit 对象为 False；候选对象损坏（`cat-file --batch-check` 同样输出 missing 但 stderr 报解包错误），或 git 读不到钉点历史（`merge-base` 此时也以 1 退出、只在 stderr 报 `Could not read`）时抛 `FactsError`，不把读失败当成"合入在钉点之后"）。钉点必须是 40 位
+  `is_ancestor(sha)`：`sha` 是钉点或其祖先（非完整 40/64 位 SHA、镜像中不存在的对象、非 commit 对象为 False；候选对象损坏（`cat-file --batch-check` 同样输出 missing 但 stderr 报解包错误），或 git 读不到钉点历史（`merge-base` 此时也以 1 退出、只在 stderr 报 `Could not read`）时抛 `FactsError`，不把读失败当成"合入在钉点之后"）。钉点必须是完整 40/64 位
   且在仓库中存在的提交，否则构造即抛 `FactsError`。
 - `check_rules(rule_texts, observer)`：对每条（活跃）规则用 `facts.claims_in` 抽取声明，按
   `facts.observe` 在钉点观测；每条声明必须成立，`^[PR #N]` 还必须已合并进钉点历史

doc/architecture/SPEC/sdk.md

@@ -1,6 +1,6 @@
 # sdk/ —— 规范
 
-<!-- verified-against: 2026-10-02 -->
+<!-- verified-against: 2026-10-06 -->
 
 
 `Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok`
@@ -17,6 +17,18 @@
 
 ## 公开契约
 
+- 显式自适应知识协议：`ContextBudget`、`DirectClient.open_knowledge_context` /
+  `plan_adaptive` / `read_knowledge_context` / `search_knowledge_context` /
+  `related_knowledge_context` / `expand_knowledge_context`。仅 `model_content` 是实际注入
+  正文；引用没有 SDK 额外 excerpt。会话默认 24k、最大累计 64k，计量单位和实际用量
+  未知状态明确返回；规则、导航、相关知识和补读同预算。旧 v1 `plan` 默认两页/6k 不变。
+- 自适应会话支持 SHA-1/SHA-256 pin，可从私有运行 SQLite 恢复原冻结 view；签发的
+  review context 绑定完整请求。旧 v1 completion 的 SHA-1 校验不因新增知识协议放宽。
+  `allowed_knowledge_repositories` 是 DirectClient 构造时的主机权限配置，不是工具授权。
+- capabilities 的支持仓库来自固定视图 registry；新仓库不要求打包 adapter。
+  `StrictRuntimeConfig` 在 registry 已识别仓库时允许不填 forge full_name；这只提供
+  知识身份兼容，不承诺旧 Strict PR 获取链路支持所有 forge 或无 forge PR。
+
 - `get_capabilities()` / `DirectClient.capabilities()` 返回 typed
   `Capabilities`：distribution/SDK/Direct/Strict/Quality/Knowledge 版本、resource revision、支持仓库、
   expected-head/structured-result/post-false/file-lock/idempotency 能力与 worker 上限。
@@ -88,10 +100,10 @@
   validator 缺失则写前 fail closed，执行失败/超时则逐 byte rollback 全部目标页。
   同一 work checkout 的 writer 以 process 内 mutex 与位于系统临时目录的
   `flock` 串行化；等待后的 SHA 复核让第二个 stale writer 失败，不会覆盖首个结果。
-- **知识 orchestration 留在宿主**：SDK 不 clone、调用 model、管理 ledger、commit、
+- **知识出版 orchestration 留在宿主**：SDK 不 clone、调用 model、管理出版 ledger、commit、
   push、开 PR 或 schedule。ReviewBot 必须向 `KnowledgeCurator` 传 dedicated work
   checkout，并继续拥有重试、artifact 与本地补丁导出；SDK 也绝不写 packaged
-  knowledge tree。
+  knowledge tree。自适应 DirectClient 仅管理知识上下文的运行账本，不代替知识出版治理。
 - SDK、Quality API 版本常量为 `1.0.0`；Direct 为 `1.1.0`，Strict 为 `1.4.0`
   （1.1 新增 `finding_dispositions`；1.2 新增 `findings`；1.3 新增显式 recheck；
   1.4 新增 `StrictRuntimeConfig.max_workers`），Knowledge 为 `1.1.0`

doc/architecture/SPEC/thin_mcp_server.md

@@ -1,6 +1,6 @@
 # thin_mcp_server.py —— 规范
 
-<!-- verified-against: 2026-09-29 -->
+<!-- verified-against: 2026-10-06 -->
 
 `LOC ~490 · 默认 MCP：Direct 门面 + Strict 入口 · refactor-status: ok`
 
@@ -9,12 +9,17 @@
 并在被要求时桥接到 Strict。
 
 ## 功能
-七个工具：`review`（按 `mode` 分流）、`validate_direct_review`、
+十二个工具：`review`（按 `mode` 分流）、`validate_direct_review`、
 `get_review_status` / `get_review_result`（转发给 `CopilotMCP`）、
-`update_knowledge`、`doc_search`、`doc_read`。
+`update_knowledge`、`doc_search`、`doc_read`，以及显式自适应会话
+`open_knowledge_context` / `read_knowledge_context` / `search_knowledge_context` /
+`related_knowledge_context` / `expand_knowledge_context`。
 
 ## 公开契约
-上述七个工具；`build_mcp(...)`；`main()`。
+上述十二个工具；`build_mcp(...)`；`main()`。`review(knowledge_profile="adaptive")`
+返回单一实际 `model_content` 和不重复正文的引用；默认 `legacy` 保持旧契约。
+会话工具累积预算，跨仓库目标只在主机授权与 confirmed 固定依赖同时成立时可读；
+模型不能通过工具参数扩大权限。模型容量与源码/输出留白是明确配置，非探测结果。
 
 ## 不变量（**C1**、**C2**、**D1**）
 - **Direct 在这个 server 里不跑任何模型。** 它返回知识路由和一份治理契约；阅读由
@@ -60,7 +65,8 @@
 - **每个工具都声明 `ToolAnnotations`，且提示必须真实。** 审批门控的宿主（codex 对
   无注解工具逐次弹批准框，headless 下自动取消，见 #86）靠这些提示放行只读面：
   `review` 是唯一保留状态变更（预留 Strict run）与触网（Strict 子进程）的工具，
-  其余六个全部 `readOnlyHint=true`。把一个会写的工具标成只读，比不标更糟。
+  其余工具全部 `readOnlyHint=true`，相对于源码、知识内容和 forge 都只读；会话接口
+  会写主机私有运行账本。把一个会修改知识或源码的工具标成只读，比不标更糟。
   （要求 `mcp>=1.8`，注解类型自该版本起可用。）
 
 ## 边界 —— 不属于这里