feat: add phase 3 procedure evaluation gate

.gitignore

@@ -4,3 +4,4 @@ node_modules/
 fixtures/skills/docx/
 __pycache__/
 .tmp-*/
+.serena/

.pi/extensions/skill-cortex/index.ts

@@ -1,15 +1,84 @@
+import path from "node:path";
+
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { registerSkillCortex } from "../../../src/adapters/pi/index.ts";
+import { registerLearningControls } from "../../../src/adapters/pi/learning-controls.ts";
+import {
+  createDiscoverySnapshotSource,
+  defaultTenantScope,
+  registerPracticeObserver,
+} from "../../../src/adapters/pi/practice-observer.ts";
+import { LearningControlStore } from "../../../src/activation/learning-control-store.ts";
+import { LearningAssessmentStore } from "../../../src/activation/admission-store.ts";
+import { LearningControls } from "../../../src/activation/learning-controls.ts";
+import { ActivationProfileStore } from "../../../src/activation/store.ts";
+import { PracticeStore } from "../../../src/practice/store/index.ts";
+import { ExposureObservationStore } from "../../../src/exposure/index.ts";
 
 /**
  * Skill Cortex — Pi 扩展入口（project-local，经 jiti 免编译加载）。
  *
- * 仅以默认 shadow 模式注册：
- * - 不修改 systemPrompt、不注入候选卡；
- * - 不写用户级环境（不写 ~/.pi）、不 appendEntry、不创建 PracticeEvent、不调用 LLM；
- * - 摄入/检索失败 fail open，不阻断主 Agent。
+ * 接线顺序（固定，不可颠倒）：
+ * 1. `createDiscoverySnapshotSource()`：当次有界候选快照 seam（RouteSnapshotSource）；
+ * 2. `registerSkillCortex({ mode: "inject", onDiscovery: (r) => source.push(r) })`：
+ *    移除 Pi 原生全量 Skill metadata，注入有界 Top-K；仅在最终 prompt 确定
+ *    （exposedToAgent=true）后 push 快照；rewrite/ingest 失败不 push（fail open）；
+ * 3. `registerPracticeObserver({ store, projectRoot, routeSnapshotSource: source })`：
+ *    在 before_agent_start take 当次快照，经 tool_call/tool_result 观察 load_skill
+ *    （details.source_hash 必须严格 sha256），agent_settled 时校验 skillId∈候选 +
+ *    revision 精确匹配后，逐条经 policy gate append 到 project-local PracticeStore。
+ *
+ * 安全边界：
+ * - projectRoot = process.cwd()；PracticeStore.rootDir 被 Store 构造强制位于 projectRoot 内
+ *   （本入口为 <cwd>/.skill-cortex/practice）；
+ * - 不写用户级环境（不写 ~/.pi）、不 appendEntry、不调用 LLM、不启动 Phase 4；
+ * - 不配置会回显原始 error/绝对路径的 onError：诊断只走稳定的脱敏类别与 onStatus，
+ *   观察/落盘失败 fail open，不阻断主 Agent；
+ * - PracticeEvent 只含派生 hash 与受控文本，原始 prompt/路径/正文永不落盘。
  */
 export default function skillCortexEntry(pi: ExtensionAPI): void {
-  registerSkillCortex(pi);
+  const projectRoot = process.cwd();
+  const source = createDiscoverySnapshotSource();
+  const tenantScope = defaultTenantScope(projectRoot);
+  const control = new LearningControlStore({
+    rootDir: path.join(projectRoot, ".skill-cortex", "control"),
+    projectRoot,
+    tenantScope,
+  });
+  const practice = new PracticeStore({
+    rootDir: path.join(projectRoot, ".skill-cortex", "practice"),
+    projectRoot,
+  });
+  const assessments = new LearningAssessmentStore({
+    rootDir: path.join(projectRoot, ".skill-cortex", "learning-assessments"),
+    projectRoot,
+  });
+  const activation = new ActivationProfileStore({
+    rootDir: path.join(projectRoot, ".skill-cortex", "activation"),
+    projectRoot,
+  });
+  const exposure = new ExposureObservationStore({
+    rootDir: path.join(projectRoot, ".skill-cortex", "exposure"),
+    projectRoot,
+  });
+
+  registerSkillCortex(pi, {
+    mode: "inject",
+    onDiscovery: (result) => source.push(result),
+    onSearchExposure: (candidates) => source.exposeSearchCandidates(candidates),
+  });
+
+  registerLearningControls(
+    pi,
+    new LearningControls(control, assessments, practice, activation, tenantScope),
+  );
+
+  registerPracticeObserver(pi, {
+    store: practice,
+    projectRoot,
+    routeSnapshotSource: source,
+    learningEnabled: async () => (await control.status()).learningEnabled,
+    onExposure: (record) => exposure.append(record),
+  });
 }

AGENTS.md

@@ -4,21 +4,26 @@
 
 ## 1. 当前项目目标
 
-- 主研究：用户已安装的声明式 Skill 如何在真实、可归因的反复使用中逐渐形成经过验证的部分程序快路径。
-- 辅助方向：prompt 外 Skill discovery，以及由使用证据派生的 Activation Memory。
+- 主研究：低打扰的 prompt 外 Skill discovery，以及由真实、可归因证据派生的 Activation Memory。
+- 整体原则：少打扰 Agent、少塞上下文、只记真正有效或经过验证的边界经验。
 - Router 不是主研究；MVP 不增加 Router LLM，不建立 Ability/category 硬门。
-- 成熟度减少的是重复读取 `SKILL.md` 与重复规划，不得用来提高 discovery 相关性。
+- Procedural Memory 已由 ADR-0014 降级为 frozen experimental track：不删除现有代码，但不新增能力、
+  不接生产入口、不作为当前完成标准。除非用户明确授权 procedure 审计/安全修复，不得继续该方向。
 
 ## 2. 开工前必读顺序
 
 1. `README.md`
-2. `docs/adr/0006-dual-memory-skill-architecture.md`
-3. `docs/adr/0007-prompt-external-skill-discovery.md`
-4. `docs/adr/0008-practice-evidence-and-procedure-promotion.md`
-5. `docs/design/dual-memory-data-contracts.md`
-6. `docs/plans/2026-08-14-dual-memory-implementation-plan.md`
+2. 最新的 `docs/reviews/*implementation-progress-audit.md`
+3. `docs/adr/0014-activation-memory-first-scope.md`
+4. `docs/design/activation-memory-first-architecture.md`
+5. `docs/adr/0007-prompt-external-skill-discovery.md`
+6. `docs/adr/0008-practice-evidence-and-procedure-promotion.md`（只适用 Practice/Activation 条款）
+7. `docs/adr/0013-selection-time-skill-memory-context.md`（evaluation-only）
+8. `docs/design/dual-memory-data-contracts.md`（procedure/runtime 部分为冻结兼容合同）
 
-ADR-0001 至 ADR-0004 和带 historical/superseded 标记的研究、审查文档只用于理解决策历史，不得作为当前实现依据。ADR-0005 只约束其 applicability note 声明的评估证据。
+只有任务明确涉及 frozen procedure 资产时，才继续读取 ADR-0006、ADR-0011、ADR-0012 与旧双记忆
+实施计划。ADR-0001 至 ADR-0004 和带 historical/superseded 标记的材料只用于决策历史。
+ADR-0005 只约束其 applicability note 声明的评估证据。
 
 ## 3. 环境与文件安全
 
@@ -32,13 +37,15 @@ ADR-0001 至 ADR-0004 和带 historical/superseded 标记的研究、审查文
 ## 4. 架构硬约束
 
 - `SkillRecord` 保存作者声明和不可变 revision；派生记忆不得覆盖原始 description、scope、权限或正文。
-- Activation Memory 回答“何时可能使用”；Procedural Memory 回答“选中后自动执行多少”。两者不得共享一个模糊 maturity score。
-- `CompiledProcedure` 必须绑定父 `skill_id + revision + dependency fingerprint`，不得成为独立全局 Skill 或 discovery 候选。
+- Exposure Gate、Candidate Budget 与 Learning Admission 是三个独立 seam，不得共享一个模糊 maturity score。
+- “任务完成”与“Skill 有贡献”必须分开验证；positive Memory 只接受 verified contribution。
+- verified negative、near-miss 与 boundary evidence 可以进入负向资料；`mixed/unknown` 不得 consolidation。
 - source、工具 schema、权限或相关依赖变化后，受影响 procedure 必须先失效再验证。
 - procedure 命中不得绕过 authorization、审批、sandbox 或父 Skill 权限。
 - 条件、依赖、授权或后置验证失配时必须停止快路径，回退到父 `SKILL.md + LLM` 或合法 abstain。
-- MVP 只允许确定性、可回放、只读或幂等操作；禁止任意自修改程序和不可补偿的自动副作用。
-- 全量 Skill catalog 保存在 prompt 外；只向主 Agent 注入候选卡。全量 metadata 仅作离线 comparator。
+- 上述 procedure 条款只约束 frozen 资产，不授权新 procedure 工作或 active 接线。
+- 全量 Skill catalog 与完整 ActivationProfile 保存在 prompt 外；只在 Exposure Gate 通过后注入最少轻量候选卡。
+- 相关不等于必须使用；能直接可靠完成且 Skill 无明显增益时优先 No-Skill。
 
 ## 5. 开发与多 Agent 协作
 
@@ -48,12 +55,14 @@ ADR-0001 至 ADR-0004 和带 historical/superseded 标记的研究、审查文
 - 采用最小、可归因改动；不要顺手重构、增加推测性抽象或提前实现后续阶段。
 - schema、权限、持久化、生命周期或执行路径的重大变化必须先新增或更新 ADR。
 - 测试数据、生产 trace 和 synthetic/evaluation 数据必须分区；当前 Agent 选择不能自动成为 gold label。
-- 每阶段按 implementation plan 的依赖、验收与 anti-pattern guard 执行；上游 gate 未通过不得启动下游 active path。
+- 当前实施按 `activation-memory-first-architecture.md` 的 D0～D4 与 G1～G7 执行；上游 gate 未通过不得启动下游 active path。
+- 开始新 Phase 前必须读取最新的 implementation progress audit；其中未关闭的 blocker 优先于 implementation plan 的下游任务。若状态冲突，以最新且有证据支持的 audit 为准，直到 blocker 被验证关闭。
+- 阶段状态必须分别报告 component implemented、host integration complete 与 end-to-end complete；仅凭 unit test、typecheck 或 code review 不得宣称整个 Phase complete。关闭 blocker 必须附对应测试、复现或真实端到端证据。
 
 ## 6. 验证与交付报告
 
 - 修改前确认适用测试；修改后运行相关单元、合同、集成和安全测试。
-- 任何 active `ActivationProfile` 必须先经过 shadow；任何 procedure 快路径必须先经过独立验证，再经过明确的 canary/promotion gate。Procedure 的 shadow replay 是一种验证方法，不是 `CompiledProcedure` 状态。
+- 任何 active `ActivationProfile` 必须先经过 shadow；frozen procedure 的原有安全门继续有效，但不得据此启动新快路径。
 - 不得用一个加权总分掩盖召回、安全、成功率、回退或成本回归。
 - 完成任务时报告：修改文件、运行命令、测试结果、未解决风险、阻塞项和可交给下一 Agent 的边界。
 - 没有实际证据时明确写“未验证”，不得把设计合同表述为已经可用的宿主能力。

CLAUDE.md

@@ -0,0 +1,101 @@
+# Claude Leader 项目说明
+
+本文件是给接管本项目统筹的 Claude（leader）看的项目级说明。所有执行 Agent（pi）的通用规范见 `AGENTS.md`；本文件补充 leader 视角的统筹、验收、决策与协作要点。二者冲突时以 `AGENTS.md` 与最新 ADR 为准。
+
+## 1. 项目目标
+
+研究「已安装 Skill 的经验引导式熟练化」，两个相互独立的问题：
+
+1. 不把全部 Skill metadata 常驻上下文时，Agent 如何发现相关已安装 Skill（prompt 外 discovery）。
+2. Agent 在真实使用一个已安装 Skill 的过程中，把稳定、可验证部分逐步固化为程序快路径（Procedural Memory）。
+
+核心对象始终是用户已安装的 Skill；程序化产物是它的派生执行表示。不研究「从自由任务轨迹自动创造全新 Skill」。
+
+## 2. 权威阅读顺序
+
+1. `AGENTS.md` —— 所有 Agent 的 project-local、安全、协作规则。
+2. `docs/reviews/2026-08-14-implementation-progress-audit.md` —— 真实阶段状态 + 未关闭 blocker（leader 决策依据）。
+3. `docs/plans/2026-08-14-dual-memory-implementation-plan.md` —— Phase 0～7、所有权、gate、验证、停止条件。
+4. `docs/adr/0006-dual-memory-skill-architecture.md`、`0007-prompt-external-skill-discovery.md`、`0008-practice-evidence-and-procedure-promotion.md`。
+5. `docs/design/dual-memory-data-contracts.md` —— 规范字段、不变量、状态机。
+6. 各 phase gate 报告（`docs/reports/`）。
+
+ADR-0001～0004 与带 historical/superseded 标记的文档只用于理解决策历史，不作当前实现依据。
+
+## 3. 当前阶段状态（动态，以最新 audit 为准）
+
+| Phase | 状态 |
+|---|---|
+| 0 宿主核验与基线 | Complete |
+| 1 Registry 与 prompt 外 discovery | Complete（B1/B2 关闭） |
+| 2 Practice Store 与证据治理 | Complete（B3 关闭，真实 observer 接线） |
+| 3 离线编译与晋升 | Complete（procedure `validated`，Gate P3 正式闭环） |
+| 4 Execution Resolver | Component + host integration（shadow）+ E2E complete；生产入口接线与 canary/active 未启动 |
+| 5 生命周期、失效与回滚 | Complete（Gate P5 PASS：失效矩阵 + rollback + host E2E）；真实宿主部署未启动 |
+| 6 Activation Memory | Complete（Gate P6 held-out PASS + host integration E2E：observer→induction→store→受控 promotion→active overlay） |
+| 7 系统验证与交接 | Complete（三 seam 关闭：search_skills overlay / host lifecycle cascade / 冻结 real-skill 评估 provider；六层验证见 [Phase 7 报告](../docs/reports/2026-08-16-phase7-validation.md)） |
+
+硬规则：上游 gate 未通过不得启动下游 active path。Phase 0～7 的 component / host integration（shadow）/ end-to-end 均已验收关闭；生产入口（.pi/extensions/skill-cortex/index.ts）接线与真实 canary/active 部署仍未启动（real-host 前 blocker：Selection 模型侧评测、crash consistency/WAL、真实宿主指纹来源）。关闭 blocker 必须附测试、复现或真实端到端证据。
+
+## 4. 版本漂移边界（2026-08-15 决策，重要）
+
+- 仓库 `package.json` / `node_modules` 锁定 `@earendil-works/pi-coding-agent@0.84.1`，测试基线用 0.84.1 runner。
+- 真实宿主 `pi` CLI 已升级到 **0.84.2**。
+- 决策（用户拍板）：**保守处理** —— observer 不硬编码 host version（`environmentFingerprint` / `dependencyFingerprint.environmentClass` 省略），仓库依赖与测试基线保持 0.84.1；0.84.2 的完整 API 核验留作后续单独任务。
+- 任何新代码不得硬编码宿主版本；无法从已验证宿主 API 可靠取得的字段一律省略，不得谎报。
+
+## 5. 架构硬约束（摘要，完整见 AGENTS.md §4）
+
+- `SkillRecord` 保存作者声明与不可变 revision；派生记忆不覆盖原文。
+- Activation Memory（何时用）与 Procedural Memory（执行多少）分离，不混一个 maturity score。
+- `CompiledProcedure` 必须绑定父 `skill_id + revision + dependency fingerprint`，不独立注册为 Skill。
+- 条件/依赖/授权/后置验证失配必须停止快路径，回退父 `SKILL.md + LLM` 或合法 abstain。
+- MVP 只允许确定性、可回放、只读或幂等操作。
+- 全量 Skill catalog 在 prompt 外；主 Agent 只注入候选卡。
+
+## 6. 环境与文件安全（完整见 AGENTS.md §3）
+
+- 目标根目录 `D:\Users\a1324\Desktop\skill机制`，所有开发/数据 project-local。
+- 不得写 `~/.pi`、`~/.codex`、`~/.agents`、全局配置、已安装 Skill。
+- 工作区外路径只读；外部写入需用户精确授权。
+- 原始 Skill package 只读；实验需先复制到项目内 fixture。
+- 秘密、完整对话、完整文件内容、未脱敏工具输出不得落盘。
+
+## 7. Leader 工作方式
+
+### 7.1 指挥 pi（herdr）
+
+pi 启动命令（在 herdr pane 中）：
+
+```text
+pi -ne -e .\.pi\extensions\skill-cortex\index.ts
+```
+
+herdr 常用命令：
+
+```text
+herdr agent list                                            # 各 pane agent 状态
+herdr agent read <name|pane_id> --source recent-unwrapped --lines N   # 读输出
+herdr agent prompt <name|pane_id> "<任务>"                    # 派活（原子发送 + Enter）
+herdr agent wait <name> --until blocked --timeout T           # 等某状态
+```
+
+派活要点：明确分配文件（一个 Agent 只改 leader 分配的文件）；给验收标准；禁止跨文件/跨 phase；禁止 pi 做全盘 find/grep 递归（会卡死）。
+
+### 7.2 验收三层口径
+
+每 phase 分别报告 **component / host integration / end-to-end**；unit test、typecheck、code review 不能宣称整 phase complete。
+
+### 7.3 git 管理
+
+- 及时提交，不积攒大量未提交改动；临时脚本（`.tmp-*`）与 `.skill-cortex/` 不入库。
+- 每个可验证完成的 Agent 交付单独或合并 commit，消息注明归属。
+- 未通过验收的半成品不 commit。
+
+## 8. 验证命令
+
+```text
+npm test            # node --test（全量）
+npm run typecheck   # tsc --noEmit
+git diff --check    # 空白/冲突检查
+```