Add governed self-evolution for Copilot workflows

doc/README.md

@@ -19,6 +19,7 @@
 | [`guide/backends.md`](guide/backends.md) | **后端**：五个 provider 怎么选、怎么配、权限如何保持（Strict） |
 | [`guide/hosts/`](guide/hosts/README.md) | **宿主端**：在 Codex / Claude Code / Cursor 里使用 copilot（Direct） |
 | [`guide/mcp.md`](guide/mcp.md) | MCP 安装与七个工具接口 |
+| [`guide/self-evolution.md`](guide/self-evolution.md) | 用自进化引擎改进评审、知识摄取与引擎自身 |
 | [`guide/metrics.md`](guide/metrics.md) | 每次运行的 `metrics.json` 消费契约（看板/统计用） |
 | [`guide/autonomous-workflow.md`](guide/autonomous-workflow.md) | 独立执行器（默认不注册） |
 | [`guide/knowledge-maintainer.md`](knowledge/maintainer-walkthrough.md) | 知识维护实操 |

doc/architecture/SPEC/chat.md

@@ -1,6 +1,6 @@
 # chat.py —— 规范
 
-<!-- verified-against: 2026-08-25 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~497 · 接口（对话式 REPL） · refactor-status: split-candidate`
 
@@ -43,3 +43,7 @@ repo_read/repo_grep/resume_run）；`ChatSession`（**永不切开工具对**的
 **建议拆分**：`chat_tools.py`（定义 + `_dispatch_tool` + 囚笼）与
 `chat.py`（会话/回合循环）。读取囚笼（`_allowed_roots`/`_check_read`）具有通用价值 ——
 如果还有别的面需要受囚笼的读取，可考虑提升为一个小的共享 helper。
+
+## 自进化接入（2026-10-04）
+
+对话任务 schema 和系统提示词包含 `workflow_improve`；调用仍经同一个 `run_task` 门，不扩大执行权限。

doc/architecture/SPEC/cli.md

@@ -1,6 +1,6 @@
 # cli/ —— 规范
 
-<!-- verified-against: 2026-09-28 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~1420（6 个文件） · 接口 + 编排门面 · refactor-status: ok`
 
@@ -93,3 +93,7 @@ flag CLI 与 `Copilot` 门面：解析 → 过门 → 执行；并持有 run 目
 
 ## 2026-09-28 kb 子命令
 `infermatrix-copilot kb …` 在 argparse 之前分派到 `kb_service.cli.main`（知识服务运维命令），不启动 Copilot/LLM。
+
+## 自进化接入（2026-10-04）
+
+`infermatrix-copilot improve …` 在通用 argparse 之前分派到 `improve.cli.main`；工作流检查、候选生成、实验、发布和账本查询使用该入口。

doc/architecture/SPEC/config.md

@@ -1,6 +1,6 @@
 # config.py —— 规范
 
-<!-- verified-against: 2026-10-01 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~658 · 配置 · refactor-status: oversized`
 
@@ -91,3 +91,7 @@ provider 的缺省模型必须在**这一处**解析，否则 `ResolvedTarget.mo
 
 注意：tier 模型名指向 RAW-API 模型，对 harness CLI 无意义，**绝不**转发过去；
 为空时回落到 `strict_backend_model`，再回落到 harness 自身默认值。
+
+## 自进化接入（2026-10-04）
+
+`TRACE_STORE_ROOT` 控制 trace/1 全量采集。`IMPROVE_ENABLED=false` 是总停止开关，`IMPROVE_EVOLVE_ENABLED=false` 控制代码进化；源码、数据和发布 outbox 各有独立目录。周预算默认 20 美元，周度槽位默认周一 05:00 UTC。`PR_CONTEXT_SOURCE=snapshot` 与 `IMPROVE_SHADOW` 由可信实验控制器设置；`KB_DRAFT_MAX_OPERATIONS` 默认 6。

doc/architecture/SPEC/engine/agent_runtime.md

@@ -1,6 +1,6 @@
 # engine/agent_runtime/ —— 规范
 
-<!-- verified-against: 2026-10-02 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~1690（7 个文件） · 引擎（受治理的 agent 运行时） · refactor-status: ok`
 
@@ -108,3 +108,7 @@ step 专属的 prompt/lens 住在各自的 step 文件里（例如 `steps/review
 cheap-seat 与按 pass 路由、MoA harness 成员、考古工具）。有两条教训被编码在上面的不变量
 里而不是写成散文：**预算保证属于代码，不属于 prompt**；以及**无法履约的路由决策必须
 大声失败** —— 因为本轮战役已经测到过三条与其标签不符的 arm。
+
+## 自进化接入（2026-10-04）
+
+影子 agent 使用严格只读 scope，知识检索与 repo map 受读根约束，拒绝知识写入工具。API 与 harness 调用均记录 trace/1；工作流的采集和配置指纹由执行器绑定，普通生产运行保持既有工具能力。

doc/architecture/SPEC/engine/executor.md

@@ -1,6 +1,6 @@
 # engine/executor.py —— 规范
 
-<!-- verified-against: 2026-09-26 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~293 · 引擎底座（那个循环） · refactor-status: ok`
 
@@ -54,3 +54,7 @@ helper：`_eval_when`、`_merge`。
 （它曾是 v2 的头号缺陷）—— **不要在没有重跑 resume 完整性测试的情况下"简化"它**。
 如果将来加入 DAG 边（目前只有有序列表），请把它们留在这里、藏在同一个 `RunOutcome`
 契约之后。
+
+## 自进化接入（2026-10-04）
+
+配置 trace 根时为整次执行绑定 store，并为每步绑定工作流、item、unit_id 和配置指纹；终局 `step_result` 保存实际报告与发现。影子运行在进入步骤前拒绝非 read/report 风险。已采用的配置覆盖按工作流限定，同时复制 LLM 的 settings，采集指纹与实际执行配置一致。

doc/architecture/SPEC/engine/steps/__init__.md

@@ -1,6 +1,6 @@
 # engine/steps/__init__.py —— 规范
 
-<!-- verified-against: 2026-09-28 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~34 · step 库聚合 · refactor-status: ok`
 
@@ -41,3 +41,7 @@ import `_common` 而不加载领域模块。调用 `register_builtin_steps` 时
 
 ## 2026-09-28
 `_BUILTIN_MODULES` 增加 `knowledge`（知识服务步骤）。
+
+## 自进化接入（2026-10-04）
+
+内置步骤注册表包含 `improve` 模块；其步骤契约见 [improve 步骤规范](improve.md)。

doc/architecture/SPEC/engine/steps/improve.md

@@ -0,0 +1,25 @@
+# engine/steps/improve.py —— 规范
+
+<!-- verified-against: 2026-10-04 -->
+
+## 职责
+
+将工作流改进服务接入 StepRegistry。算法、评估及持久化契约见 [改进引擎规范](../../improve.md)；操作入口见 [中文使用指南](../../../../guide/self-evolution.md)。
+
+## 公开契约
+
+`improve.stage_items` 准备冻结输入；`improve.mode` 区分周度周期、进化协调器和元基准 case。`improve.preflight/sync/lint/experiments/forensics/ledger/report` 保留 P0–P4 周期。`improve.coordinate` 调用 CLI 和调度器共用的可续跑协调器。
+
+`improve.forensics` 只读指定工作流和仓库的 trace；归因输出引用记录 ID。旧配置元基准路径调用 `meta.run_case` 生成 `meta_eval`；源码版本化实验则由可信父进程评分，候选 worker 只接收 case 输入，不接收人工标签。
+
+## 不变量
+
+- 读取 trace store 优先使用当前绑定实例，未绑定时使用 Settings 的根目录；缺根时阻塞或返回明确跳过原因。
+- `improve.publish` 和 `improve.evolve_publish` 为 push 风险，影子执行器在运行前拒绝。
+- 进化发布只接受 pr-ready 制品；任务 post、ALLOW_POST、ALLOW_PUSH 均须开放，发布准备仍由可信父进程验证。
+- `IMPROVE_ENABLED` 是总停止开关；元基准模式不顺带运行周度周期或发布。
+- 知识摄取候选仅在隔离输入中验证，不写生产知识库。
+
+## 测试
+
+`test_improve_p0b.py`、`test_improve_p1.py`、`test_improve_p2.py`、`test_improve_p3.py`、`test_improve_p4.py`、`test_evolution.py`。

doc/architecture/SPEC/engine/steps/knowledge.md

@@ -1,6 +1,6 @@
 # engine/steps/knowledge.py —— 规范
 
-<!-- verified-against: 2026-10-02 -->
+<!-- verified-against: 2026-10-04 -->
 
 `知识服务的 knowledge.* 步骤 · refactor-status: new`
 

doc/architecture/SPEC/engine/steps/pr.md

@@ -1,6 +1,6 @@
 # engine/steps/pr/ —— 规范
 
-<!-- verified-against: 2026-10-02 -->
+<!-- verified-against: 2026-10-04 -->
 
 `LOC ~1988（6 个文件） · step 库（PR） · refactor-status: ok`
 
@@ -122,3 +122,7 @@ BLOCK、worktree 分键/拒外来树、report-only rebase 的隔离与失效树
 读/写轴是显式的：`fetch` 只读，`publish` 装着两个 risk=push 的 step。
 K3/K4/K7 的精简（require_repo/published/from_state）已在各子模块落地。
 `_enrich_ci_logs` 保持为通往 `ci/providers` 的**薄接缝**。
+
+## 自进化接入（2026-10-04）
+
+影子模式下 `pr.fetch_diff`、gate 和 CI 取数从可信控制器准备的 `pr_snapshot` 读取；快照缺少必要字段即阻塞，不回退到实时网络。基线和候选共用冻结的 base/head 与上下文。

doc/architecture/SPEC/engine/steps/review.md

@@ -1,6 +1,6 @@
 # engine/steps/review/ —— 规范
 
-<!-- verified-against: 2026-10-02 -->
+<!-- verified-against: 2026-10-04 -->
 
 `patch gate + PR review + quality（9 个源文件） · step 库（评审） · refactor-status: ok`
 
@@ -134,3 +134,7 @@ agent、评审结果的有界精炼、评测调优过的 prompt 数据和确定
 ## Carried finding rechecks
 
 Direct 1.1 / Strict 1.3 accept typed `CarriedFinding` inputs (unique IDs, source head, severity, location, title and evidence). Direct binds the carried set into its issued context and validates `FindingRecheck` answers. Strict passes the set through the policy allowlist, performs a read-only recheck against the frozen PR head, and persists answers for the public structured result. Every carried ID needs an explicit outcome: `fixed`, `still_affected`, or `unverified`. Missing evidence is never a fix.
+
+## 自进化接入（2026-10-04）
+
+影子评审继承严格工具 scope；PR 文件、基础版本与历史工具只能读取冻结仓库，涉及生产写入的步骤由执行器拒绝。

doc/architecture/SPEC/improve.md

@@ -0,0 +1,59 @@
+# improve/ —— 规范（元改进引擎）
+
+<!-- verified-against: 2026-10-04 -->
+
+`设计：/data/zhoutaichang/copilot/meta-improvement-engine-design.md v1（GPT-6 sol 批准 2026-09-29） · refactor-status: building (P0–P4 已落地)`
+
+## 职责
+面向任意 trace/1 工作流的"取证—候选—实验—人审 PR—上线观察"循环。使用入口和数据契约见 [自进化使用指南](../../guide/self-evolution.md)。引擎的写权限限于追加自己的 trace/1 记录、
+写自己的账本和源码制品目录、在 OS 隔离环境跑候选；产线变更一律走人审 PR。
+
+新增 `artifacts.py`（不可变源码及补丁）、`isolation.py/worker.py`（无凭据沙箱与可信预算代理）、`drivers.py`（PR/知识/元基准驱动及父进程评分）、`evolution.py`（周度候选状态机）、`coordinator.py`（统一续跑周期）、`annotations.py`（历史 trace 导出与人工标签导入）、`evolution_publish.py`（独立 `evolve-outbox/1` 与部署跟踪）。`IMPROVE_EVOLVE_ENABLED` 默认关闭，`IMPROVE_ENABLED` 保留总停止作用。
+
+## 模块
+| 文件 | 阶段 | 作用 |
+|---|---|---|
+| `enroll.py` | P0 | 工作流声明（`workflows/*.yaml` + `IMPROVE_WORKFLOWS_DIRS`）：kind/unit/item_key/fingerprint.covers/capture/shadow_tools；未声明 = Tier 1 |
+| `fingerprint.py` | P0 | 声明式配置指纹（playbook sha、settings、prompt 文件哈希、routing、`resolved_models`、tools、knowledge_snapshot、copilot_sha）；覆盖项缺失 → 无指纹、记 `fingerprint_missing` |
+| `shadow.py` | P0 | 影子四层边界：`harden_scope`（严格 extra、读围栏）、`shadow_env`/`make_executables_dir`/`assert_boundaries`（凭据与可执行白名单）、`make_shadow_clone`（`--shared` 独立克隆、无 remote、钉住的 base ref）、`smoke` |
+| `staging.py` | P0 | 隔离前的条目快照：`stage_item` 复用 `pr.fetch_diff` 的钉住取数，写 `item_staged` 记录；任一必需输入不可得即拒绝 |
+| `reader.py` | P1 | trace/1 → 工作单元（按 `context.unit_id`，RB/知识服务记录回退到 `run_id:step`）；窗口按 JSONL 日期文件读取 |
+| `lints.py` | P1 | Tier 1 的 17 条确定性 lint（L01–L17，每条带版本与出处）；`Baseline` 稳健 z（MAD 下限 = 中位数的 10%）；L13 隔离 |
+| `ledger.py` | P1 | 每工作流 JSON 账本：周期统计、基线样本、提案状态机（open → experiment-registered → supported/neutral/refuted/underpowered → landed/closed；30 天无人触碰 → stale）、hold、通道活性；每次变更同时写 `decision` |
+| `cycle.py` | P1 | 周期：preflight（`improve_enabled` 是 kill switch）→ lints + 基线 → 账本 + Tier 1 提案（lint 恶化 ≥1.5× 且 ≥3 单元）→ stale 清扫 → 报告（`reports/cycle-*.md/json`）+ `decision(type=cycle)`；`is_due`/`maybe_run_weekly` 是周度槽位 |
+| `adapters/__init__.py` | P2 | 结果适配器契约：金标矩阵（`match()` → recall 与阶段归因）与 finding 级有效性（`findings()` → precision）两个数据模型不混用；评审级判官分数（`review_scores()`）原样保留；`scores_from` 给每个数字标来源 |
+| `gold.py` | P2 | 策展金标集：`gold_id = sha256(item+path+规范化 concern)[:12]`，`draft` 由原始评论生成、只有 `curated` 才被使用，改措辞即新条目，文件 sha 即版本 |
+| `judges.py` | P2 | `run_judge`：API 判官走 `LLM.create`，CLI 判官走 `governed_subprocess`（预留判官次数、无工具、空工作区、流中出现工具调用即作废），都写 `model_call` |
+| `stats.py` | P2 | 配对、按 item 聚类的 t 区间（移植 `paired_analysis.py`）、所需 item 数、五种标签、Cohen κ |
+| `adapters/review_eval.py` | P2 | eval 评审适配器：导入 `judge_val` 配对 verdict 为 `judge_verdict` outcome；`gold_match` 判官（3 票多数、hit 须逐字引用）写 `gold_match` outcome；`match()` 只读记录 |
+| `adapters/rb_review.py` | P2 | RB 生产适配器：PR 线程代理标签（accepted/disputed/silent）→ finding 级有效性，`descriptive_only`，无金标、不注册实验 |
+| `adapters/kb_intake.py` | P2+ | 知识起草（`kb-intake.draft`）适配器：结果 = 生产质量门本身写的 `gate_block`/`gate_summary` outcome；finding 级有效性 = L2 判定（pass=valid、fail=invalid、unsure=unlabeled），评审级分数 = `net_pass`/`gate_score`/`precision`/`yield_pass`/`fail`/`human`/`empty`；金标 = 该 item 上在位生成器通过门禁的规则（`gold_from_incumbent` → `write_gold`，按内容版本化），`gold_match` 判官 3 票多数、hit 须逐字引用，空稿不调判官直接 miss |
+| `workflows/kb-intake.yaml` | P2+ | 起草步骤的声明：static/step_call，item `{repo}#{pr}`，指纹覆盖 `kb_service/intake.py`、`KB_GENERATOR`/`KB_DRAFT_STRATEGY`、`zcode_reasoning_level`、copilot_sha；`kb_service.runtime` 为每次起草盖上 workflow/unit_id/item/fingerprint |
+| `forensics.py` | P2 | 覆盖矩阵（确定性）、S0–S10 阶段分类法、取证 agent（只读 trace 工具、全部输出围栏为不可信数据、必须引用记录 id）、双家族交叉复核（不一致 = disputed）、整改清单、测量健康 |
+| `meta.py` | P2 | 冻结元基准：`eval/dataset/meta/cases`（trace + 人工阶段标签）与 `meta/lints`（注入缺陷样本）的导出与加载 |
+| `budget.py` | P3 | 周包络（美元 + 判官次数，按 ISO 周持久化、跨进程加锁）：每次模型调用发出前按最坏情况预留（输入 = 请求字节数 ≥ token 数、输出 = `max_tokens`、无价格即拒绝）、返回后结算；`结算 > 预留` 记 `budget_breach` 并中止；`governed()`/`current_governor()` 供 `LLM.create` 与 `run_judge` 使用 |
+| `experiments.py` | P3 | 预注册（Tier 2 且非 descriptive-only、API 后端、指纹 diff 非空且不触及元基准、每个 item 有金标、按历史 sd 算 `n_required`、成本预留）→ 影子运行（stage → 每 item×replicate×臂 一个子进程、`PR_SNAPSHOT_FILE` 交接、指纹核对、L13/预算/崩溃隔离）→ 配对判定（`n_retained` 重算功效、五种标签、`experiment_verdict` 记录、提案状态推进） |
+| `publish.py` | P4 | 提案发布：引用只以记录 id + blob 哈希（`excerpt_for` 逐字摘录 ≤20 行、脱敏、`verify_excerpt` 可由哈希复原）；`lint_proposal` 拒绝任何不可解析引用（Tier 1 ≥3 条记录，Tier 2 S1–S9 + 损失量）；固定 issue 模板（主张/阶段/损失/证据/建议预注册/账本/marker）；`ProposalOutbox` 文件协议 `improve-outbox/1`（`actions/` 引擎写、`acks/` 与 `inbox/` maintainer routine 写）；`plan`/`publish`（open/update/close，hold 暂停发布、待 ack 不重发）；`sync`（ack → issue 与已发布状态；inbox → 人类触碰、`maintainer: hold`、合并 PR → landed、GitHub 关闭 → closed；Tier 1 landed 在后一周期 lint 率低于开单时才 close） |
+| `adapters/meta_bench.py` | P4 | 引擎自身的结果适配器（§11.2）：金标 = 元基准 case 的人工阶段标签；outcome = `meta_eval` 记录；hit = 标签一致、disputed = 双家族不一致、S0 = unlabeled；`review_scores` = κ、lint 召回；`human_labelled`（无判官） |
+| `workflows/workflow-improve.yaml` | P4 | 引擎自登记：`workflow-improve.improve.forensics`，item `{improve_item}`（周期为 `cycle`、自实验为 `meta:<case>`），指纹覆盖取证/lint/统计/适配器源码与模型 |
+| `cli.py` | P0–P4 | `improve migrate-index|rebuild-index|rollback-index|compare-index|verify-index|cycle|ledger|lints|gold draft/check|meta lint-check/bench|budget|experiment register/run/list|publish [--dry-run]|sync` |
+
+## 接入点
+- 执行器：`settings.trace_store_root` 非空时绑定 store 并为每步绑定单元上下文；`settings.improve_shadow` 下拒绝非 read/report 步骤。
+- `tools.dispatch` / `LLM.create` / `HarnessLLM.create` / `run_harness_step` / MCP bridge：全保真采集。
+- `kb serve` 调度器：每 tick 调 `_improve_cycle()`，周度槽位到达即跑一次周期（与知识服务同一租约、异常隔离）。
+- 任务种类 `workflow_improve`（L2，READ_ONLY_KINDS）；playbook `workflow-improve`（mode → preflight → sync → lint → experiments → forensics → ledger → publish → report）；`improve.publish` 是唯一 `risk=push` 步骤，与 `pr.post_review` 同样过"TaskSpec `post` 且 ALLOW_POST=1"双门，否则 dry-run 打印将写的 outbox 动作。
+- `LLM.create`：绑定了 governor 时先预留再发请求，失败释放、成功结算；`improve.experiments` 与 `improve.forensics` 都在 `governed()` 内运行。
+- `improve.forensics` 步骤：对每个有结果适配器的工作流建覆盖矩阵、用两个模型家族归因每个 miss、产出整改清单并按阶段各开一条 Tier 2 提案（`cycle.open_tier2_proposals`，带建议预注册；descriptive-only 工作流的提案标 proxy、无建议）；单元数低于 `tier2_min_items` 或无 LLM 时跳过并说明。`--task-param meta_case=<case>` 时（`improve.mode` 发布 `improve_meta`）只跑取证步骤：对一个冻结 case 归因并写 `meta_eval` outcome——这就是自实验的影子单元（`experiments.meta_run_unit` / `_meta_stage` 只把 case 与 lint 样本复制进影子目录，不带任何叙述材料）。
+- `improve.sync`（read）读回 acks/inbox；`improve.publish`（**`risk="push"`**，唯一外向写）：无 `post` 意图只预览、有意图但 `ALLOW_POST=0` 为 dry-run、二者俱备才写 `improve_outbox_dir` 下的动作文件（`improve_proposal_repo` 必填）；影子运行被执行器在步骤前拒绝。
+- 自实验：`experiments.run` 对 `human_labelled` 适配器不要求判官；`_find_unit` 优先取声明工作流的单元。
+
+## 不变量
+- 既有提案的外向写是 `improve.publish`，代码候选另由 `improve.evolve_publish` 经 post/push 双门写独立 outbox；引擎不持有 GitHub 令牌，issue 的开/改/关由 maintainer routine 执行并以 ack 回报。
+- 未通过 `lint_proposal` 的提案永不发布（记 `proposal_lint_failed`）；hold 只暂停发布，lint 与实验照常。
+- 元基准只读：任何触及 `eval/dataset/meta` 的指纹 diff 或 `IMPROVE_*` 覆盖在注册时被拒。
+- 引擎自身的记录（`playbook=workflow-improve`）是下一周期的 Tier 1 单元（自登记）。
+- lint 只读 trace，不调模型；无证据形态的 lint 不猜。
+
+## 测试
+`test_improve_p0.py`、`test_improve_p0b.py`、`test_improve_p1.py`、`test_improve_p2.py`、`test_improve_p3.py`、`test_improve_p4.py`、`test_improve_kb_intake_adapter.py`、`test_evolution.py`。