pi-skill-evolve 0.0.0-stage → 0.1.0

package/extensions/skill-evolve/lib/evolution-observe.ts

@@ -0,0 +1,82 @@
+/**
+ * 可观测层（设计稿 14 章）的胶水：面板刷新 + 状态变迁转 `/tree` 条目 + 周报与指标落盘。
+ *
+ * 与采集/门禁隔开的原因：这里只读盘、算数、出文本，既不写技能文件也不派发进程，
+ * 单测与 evolution.test.ts 都能直接喂假目录。
+ */
+import { appendMetrics, buildMetrics, type MetricsRun } from "./metrics.ts";
+import { collectPanelState, statusEntries, type PanelEntry, type PanelState } from "./panel.ts";
+import { listRuns } from "./runs.ts";
+import { scanStaleRuns } from "./stale.ts";
+import { readEvents, type MutationQueue } from "./telemetry.ts";
+import { createWeeklyReport } from "./weekly.ts";
+
+/** 面板渲染交给 index.ts（widget / status / appendEntry 都是 pi 的能力）；这里只往外抛数据 */
+export interface PanelDeps {
+  onEntry?: (entry: PanelEntry) => void;
+  onState?: (state: PanelState) => void;
+}
+
+export interface ObserverDeps {
+  cwd: string;
+  evolutionDir: string;
+  telemetryDir: string;
+  queue: MutationQueue;
+  now: () => number;
+  /** 单 run 上限（来自配置）：pid 还活着但跑超过它也算卡死 */
+  maxRuntimeMs?: number;
+  panel?: PanelDeps;
+}
+
+export interface Observer {
+  /** settle / session_start / approve 之后调：顺带把新出现的状态变迁发成条目 */
+  refresh(): PanelState;
+  /** 派发成功时立刻记一条（此时 run.json 刚写，下一轮 refresh 才能看到） */
+  noteDispatched(runId: string): void;
+  /** `/skill-evolve report --week` */
+  weekReportText(): Promise<string>;
+}
+
+export const METRICS_WINDOW_DAYS = 28;
+
+export function createObserver(deps: ObserverDeps): Observer {
+  const panelDeps = deps.panel ?? {};
+  // 进程内记忆「上次见到的状态」：一条状态只发一次条目，不因反复刷新重复刷屏
+  const seen = new Map<string, string>();
+
+  const refresh: Observer["refresh"] = () => {
+    const now = deps.now();
+    // 先扫盘再算数：子进程已死的 run 在这里落成 stale，否则面板会永远显示「复盘 N」
+    const limit = deps.maxRuntimeMs === undefined ? {} : { maxRuntimeMs: deps.maxRuntimeMs };
+    scanStaleRuns(deps.evolutionDir, now, limit);
+    const state = collectPanelState({ evolutionDir: deps.evolutionDir, now, ...limit });
+    for (const entry of statusEntries(listRuns(deps.evolutionDir, 20), seen, now)) panelDeps.onEntry?.(entry);
+    panelDeps.onState?.(state);
+    return state;
+  };
+
+  const noteDispatched: Observer["noteDispatched"] = (runId) => {
+    seen.set(runId, "dispatched");
+    panelDeps.onEntry?.({ kind: "dispatched", runId, at: deps.now() });
+    refresh();
+  };
+
+  /** 指标落盘：按周聚合后逐行 append，同 week 已有就跳过（appendMetrics 内部去重） */
+  const weekReportText: Observer["weekReportText"] = async () => {
+    const now = deps.now();
+    const events = readEvents(deps.telemetryDir, METRICS_WINDOW_DAYS, now);
+    const runs: MetricsRun[] = listRuns(deps.evolutionDir, 50).map((run) => ({
+      runId: run.runId,
+      status: run.status,
+      dispatchedAt: run.dispatchedAt,
+    }));
+    const report = createWeeklyReport({ cwd: deps.cwd, evolutionDir: deps.evolutionDir, telemetryDir: deps.telemetryDir, now: deps.now });
+    const text = report.weekText();
+    for (const row of buildMetrics(events, now, runs)) {
+      await appendMetrics(deps.evolutionDir, row, deps.queue);
+    }
+    return text;
+  };
+
+  return { refresh, noteDispatched, weekReportText };
+}

package/extensions/skill-evolve/lib/evolution-views.ts

@@ -0,0 +1,89 @@
+/**
+ * `/skill-evolve status|report` 与 `/skill-audit` 的读盘 + 渲染（从 evolution.ts 拆出）。
+ *
+ * 拆出来的原因很实际：evolution.ts 要守 300 行闸门，而这一组只做「读状态 → 出文本」，
+ * 与采集/门禁/派发没有任何耦合，放一起反而让门禁逻辑难读。
+ */
+import * as fs from "node:fs";
+import { auditText as renderAuditText, buildAuditModel, activeToolsFromEvents, exposedFromEvents } from "./audit.ts";
+import { fingerprintsOf, type BaselineGate } from "./baseline.ts";
+import { configFile, type EvolutionConfig } from "./config.ts";
+import type { ModelTools } from "./evolution-model.ts";
+import { lockDir, readOwner } from "./lock.ts";
+import type { Mechanical } from "./mechanical.ts";
+import type { MechanicalReporter } from "./mechanical-report.ts";
+import { renderReport, renderStatus } from "./report.ts";
+import { listRuns } from "./runs.ts";
+import { listStaleRuns, scanStaleRuns } from "./stale.ts";
+import { readEvents, summarize } from "./telemetry.ts";
+import { isAlive, readWebPid } from "./web/panel-pid.ts";
+
+export interface ViewsDeps {
+  evolutionDir: string;
+  telemetryDir: string;
+  config: EvolutionConfig;
+  now: () => number;
+  mechanical: Mechanical;
+  mechanicalReporter: MechanicalReporter;
+  baselineGate: BaselineGate;
+  modelTools: ModelTools;
+}
+
+export interface Views {
+  statusText(): Promise<string>;
+  reportText(days?: number): string;
+  auditText(days?: number): Promise<string>;
+}
+
+export function createViews(deps: ViewsDeps): Views {
+  const statusText = async (): Promise<string> => {
+    const dir = lockDir(deps.evolutionDir);
+    const held = fs.existsSync(dir);
+    const owner = held ? await readOwner(dir) : null;
+    // 先扫一遍再报：子进程死掉的 run 要在这里被标成 stale，否则 status 会永远漏报失败
+    scanStaleRuns(deps.evolutionDir, deps.now(), { maxRuntimeMs: deps.config.maxRuntimeMs });
+    // Web 面板记录只在 pid 还活着时显示：残记录（kill -9 之后）不该出现在状态里
+    const web = readWebPid(deps.evolutionDir);
+    return renderStatus({
+      config: deps.config,
+      configPath: configFile(deps.evolutionDir),
+      telemetryDir: deps.telemetryDir,
+      lockPid: held ? (owner?.pid ?? null) : undefined,
+      webPanel: web && isAlive(web.pid) ? { url: web.url, pid: web.pid } : null,
+      runs: listRuns(deps.evolutionDir, 5),
+      staleRuns: listStaleRuns(deps.evolutionDir, 5),
+      selftest: deps.modelTools.lastSelftest(),
+    });
+  };
+
+  const reportText = (days = 7): string =>
+    renderReport({
+      days,
+      summary: summarize(readEvents(deps.telemetryDir, days, deps.now())),
+      runs: listRuns(deps.evolutionDir, 10),
+      selftest: deps.modelTools.lastSelftest(),
+    });
+
+  /** 机械审计：类别汇总来自遥测 attributed；历史 missed 用当前快照现算（可能是旧数据，标注清楚） */
+  const auditText = async (days = 7): Promise<string> => {
+    const events = readEvents(deps.telemetryDir, days, deps.now());
+    deps.mechanicalReporter.noteFailure();
+    const { hits, invalid } = deps.mechanical.conflicts();
+    // 先取（缺文件时在这里 bootstrap），再等写盘落地：顺序反了文件可能还在写就返回了
+    const knownFingerprints = fingerprintsOf(deps.baselineGate.baseline());
+    await deps.baselineGate.settled();
+    const exposed = exposedFromEvents(events);
+    const activeTools = activeToolsFromEvents(events);
+    const model = buildAuditModel({
+      days,
+      events,
+      conflicts: hits,
+      knownFingerprints,
+      invalidRules: invalid,
+      classify: (skill) => deps.mechanical.attribute({ missed: [skill], exposed, activeTools })[0].category,
+    });
+    return renderAuditText(model);
+  };
+
+  return { statusText, reportText, auditText };
+}

package/extensions/skill-evolve/lib/evolution.ts

@@ -0,0 +1,289 @@
+/**
+ * 主会话里的采集与门禁：曝光 / 加载 / 未命中 / 去抖派生 + 命令文本。
+ *
+ * 这一层刻意不 import pi 的任何东西：事件字段由 index.ts 拆成原始值再传进来，
+ * 这样门禁逻辑能被 node --test 直接跑，不依赖 `@earendil-works/pi-coding-agent` 的可解析性。
+ */
+import * as path from "node:path";
+import { configFile, loadConfig, saveConfigSwitch, saveFlag, type ConfigFlag, type EvolutionConfig } from "./config.ts";
+import type { Attribution } from "./attribution.ts";
+import { baselinePath, createBaselineGate } from "./baseline.ts";
+import { isChildProcess } from "./child-env.ts";
+import type { ApplyDeps } from "./apply.ts";
+import { createDispatcher } from "./dispatch.ts";
+import { createApplyTools, type ApplyTools } from "./evolution-apply.ts";
+import { createModelTools, type ModelTools } from "./evolution-model.ts";
+import { createObserver, type Observer, type PanelDeps } from "./evolution-observe.ts";
+import { createViews } from "./evolution-views.ts";
+import { flagStateText, FLAG_LABEL } from "./flags.ts";
+import type { GitRunner } from "./gate0.ts";
+import { logLine } from "./logfile.ts";
+import { createMechanicalReporter } from "./mechanical-report.ts";
+import { createMechanical, type RawDiagnostic, type SnapshotSkill } from "./mechanical.ts";
+import { createCommitRunner, createGitRunner, createMdCheckRunner } from "./proc.ts";
+import { renderManualDispatch } from "./report.ts";
+import type { SupervisorSpawn } from "./review-spawn.ts";
+import type { QueueItem } from "./queue.ts";
+import { createRoundTracker } from "./round.ts";
+import type { SpawnLike } from "./spawn-plan.ts";
+import { createTelemetry, type MutationQueue, type TelemetrySkill } from "./telemetry.ts";
+
+/** 子进程门禁在这里再导出一次：历史调用方与测试都从 evolution 取它 */
+export { isChildProcess };
+
+export interface EvolutionDeps {
+  cwd: string;
+  promptTemplatePath: string;
+  queue: MutationQueue;
+  log?: (msg: string) => void;
+  now?: () => number;
+  env?: NodeJS.ProcessEnv;
+  spawnFn?: SpawnLike;
+  /** 生产注入：() => loadSkillsFromDir({ dir: join(cwd, ".pi/skills"), source: "project" }) */
+  loadSkills?: () => { skills: SnapshotSkill[]; diagnostics: RawDiagnostic[] };
+  /** 默认 .pi/evolution/rules/hard-rules.json */
+  rulesFile?: string;
+  /** 主会话当前模型：模型配置写 inherit 时用它解析评审模型 */
+  hostModel?: () => { provider?: string; id?: string } | undefined;
+  /** 评审督导的 spawn（默认真起 node 进程；单测注入假实现，避免留 900s 的后台进程） */
+  supervisorSpawnFn?: SupervisorSpawn;
+  /** 闸0/闸3 的 git 摘要（单测注入假实现：真实 git 与本扩展无关） */
+  git?: GitRunner;
+  /** 闸3 的 md-check 子进程（单测注入假实现） */
+  runMdCheck?: (absPath: string) => { code: number; output: string };
+  /** auto 级成功后的单独 commit（单测注入假实现；不注入则用真 git） */
+  commit?: ApplyDeps["commit"];
+  /** 面板回调：widget / status / appendEntry 是 pi 的能力，由 index.ts 提供 */
+  panel?: PanelDeps;
+  /** pid 存活判定（全局单飞闸用；单测注入，测试里不起真子进程） */
+  alive?: (pid: number) => boolean;
+}
+
+export interface Evolution {
+  recordAdvertised(input: {
+    sessionId: string;
+    cwd: string;
+    prompt: string;
+    skills: TelemetrySkill[];
+    /** 本轮声明的工具名（pi.getActiveTools()）：类 E 判定的唯一依据 */
+    activeTools?: string[];
+  }): void;
+  noteToolCall(input: { sessionId: string; toolCallId: string; toolName: string; input: Record<string, unknown> }): void;
+  resolveToolResult(input: { sessionId: string; toolCallId: string; isError: boolean }): void;
+  settle(input: { sessionId: string; sessionFile?: string }): void;
+  recordHandlerError(where: string, error: unknown): void;
+  /** 手动兜底：立即派发一次（跳过去抖与上限，仍守全局锁） */
+  runNow(input: { sessionId: string; sessionFile?: string }): Promise<string>;
+  /** 退出前把还没派发的轮次补发一次；同步完成，不抛 */
+  shutdown(): void;
+  flush(): Promise<void>;
+  statusText(): Promise<string>;
+  reportText(days?: number): string;
+  /** 机械审计：类别汇总 + 硬禁令两段（存量 / 新增）+ 加载率注解 */
+  auditText(days?: number): Promise<string>;
+  /** `/skill-evolve baseline`：把当前命中全部接受为存量；reset 清空清单 */
+  acceptBaseline(mode: "accept" | "reset"): Promise<string>;
+  setEnabled(enabled: boolean): Promise<string>;
+  /** `/skill-evolve collect|review` 与 Web 控制条：只切一个开关（另一个保持原值） */
+  setFlag(field: ConfigFlag, value: boolean): Promise<string>;
+  /** 模型配置 + 必红自检（`/skill-evolve config|selftest`） */
+  model: ModelTools;
+  /** 分级采纳：闸0 快照 / 队列扫描 / 自动应用 / approve 与 queue 命令 */
+  apply: ApplyTools;
+  /** M6：面板刷新（状态变迁转 /tree 条目）与周报 + 指标落盘 */
+  observe: Observer;
+}
+
+export function createEvolution(deps: EvolutionDeps): Evolution {
+  const evolutionDir = path.join(deps.cwd, ".pi", "evolution");
+  // 默认只落盘（`.pi/evolution/logs/extension.log`）：TUI 默认零推送，PI_SKILL_EVOLVE_DEBUG=1 才回显
+  const log = deps.log ?? ((msg: string) => logLine(evolutionDir, msg));
+  const env = deps.env ?? process.env;
+  const now = deps.now ?? (() => Date.now());
+  const telemetryDir = path.join(evolutionDir, "telemetry");
+  // 配置对象全生命周期只此一份：setEnabled 用 Object.assign 原地改，派发器看到的是同一份
+  const config: EvolutionConfig = loadConfig(evolutionDir, log);
+  // 传 getter 而不是快照：on/off 当场改 config 后，采集与写入立刻跟着变
+  const telemetry = createTelemetry({ dir: telemetryDir, queue: deps.queue, enabled: () => config.telemetry, log, now });
+  // 机械层：发现结果与硬禁令扫描都按进程缓存，第一次用到才干活（factory 里不读盘）
+  const mechanical = createMechanical({
+    cwd: deps.cwd,
+    rulesFile: deps.rulesFile ?? path.join(evolutionDir, "rules", "hard-rules.json"),
+    loadSkills: deps.loadSkills ?? (() => {
+      throw new Error("未注入 loadSkillsFromDir，机械归因降级");
+    }),
+    log,
+  });
+  const modelTools = createModelTools({
+    evolutionDir,
+    cwd: deps.cwd,
+    queue: deps.queue,
+    log,
+    now,
+    env,
+    ...(deps.hostModel ? { hostModel: deps.hostModel } : {}),
+  });
+  const dispatcher = createDispatcher({
+    evolutionDir,
+    cwd: deps.cwd,
+    config,
+    telemetry,
+    queue: deps.queue,
+    promptTemplatePath: deps.promptTemplatePath,
+    log,
+    now,
+    env,
+    spawnFn: deps.spawnFn,
+    reviewModel: modelTools.reviewModel,
+    selftestFailed: modelTools.selftestFailed,
+    ...(deps.alive ? { alive: deps.alive } : {}),
+    ...(deps.supervisorSpawnFn ? { supervisorSpawnFn: deps.supervisorSpawnFn } : {}),
+  });
+
+  const applyTools = createApplyTools({
+    evolutionDir,
+    cwd: deps.cwd,
+    queue: deps.queue,
+    log,
+    now,
+    git: deps.git ?? createGitRunner(),
+    // 闸3 的技能诊断直接复用 mechanical 的发现结果，避免第二次 readdir 出不一致的结论
+    loadDiagnostics: () => (deps.loadSkills ? deps.loadSkills().diagnostics : []),
+    runMdCheck: deps.runMdCheck ?? createMdCheckRunner(deps.cwd),
+    ...(deps.commit ? { commit: deps.commit } : { commit: (item: QueueItem) => createCommitRunner(deps.cwd)(item) }),
+  });
+
+  const observer = createObserver({
+    cwd: deps.cwd,
+    evolutionDir,
+    telemetryDir,
+    queue: deps.queue,
+    now,
+    maxRuntimeMs: config.maxRuntimeMs,
+    ...(deps.panel ? { panel: deps.panel } : {}),
+  });
+
+  /** 最近一轮的技能集 / 会话文件 / 归因：服务手动 `/skill-evolve run`，它可能发生在 settle 之后 */
+  const lastRound = new Map<string, { skills: string[]; sessionFile?: string; activeTools: string[]; attributions: Attribution[] }>();
+  // 存量债基线（设计稿 10.4）：懒加载，首次审计时把当时全部命中当存量
+  const baselineGate = createBaselineGate({ file: baselinePath(evolutionDir), hits: () => mechanical.conflicts().hits, now, queue: deps.queue, log });
+  const mechanicalReporter = createMechanicalReporter({ mechanical, append: (event) => telemetry.append(event), log, stockOf: baselineGate.isStock });
+  // 一轮内的曝光/加载状态机（内存态）：本层只关心结算结果与派发时机
+  const rounds = createRoundTracker({ cwd: deps.cwd, append: (event) => telemetry.append(event) });
+
+  const recordAdvertised: Evolution["recordAdvertised"] = (input) => {
+    const activeTools = input.activeTools ?? [];
+    rounds.recordAdvertised({ ...input, activeTools });
+    lastRound.set(input.sessionId, {
+      skills: input.skills.filter((skill) => !skill.disabled).map((skill) => skill.name),
+      sessionFile: lastRound.get(input.sessionId)?.sessionFile,
+      activeTools,
+      attributions: [],
+    });
+  };
+
+  const noteToolCall: Evolution["noteToolCall"] = (input) => rounds.noteToolCall(input);
+  const resolveToolResult: Evolution["resolveToolResult"] = (input) => rounds.resolveToolResult(input);
+
+  const settle: Evolution["settle"] = (input) => {
+    // 评审督导是独立进程、可能刚写完 03-review.json：每轮都扫一次队列，auto 条自动落盘
+    if (!isChildProcess(env)) applyTools.settle();
+    const result = rounds.settle(input.sessionId);
+    if (!result) return;
+
+    // 机械归因（A~E）+ 硬禁令扫描：只记事实，判不动的标 semantic 交给复盘 agent 做 F/G
+    const attributions = mechanicalReporter.report({
+      sessionId: input.sessionId,
+      exposed: result.exposed,
+      missed: result.missed,
+      activeTools: result.activeTools,
+    });
+
+    if (isChildProcess(env)) return; // 门禁⓪
+    lastRound.set(input.sessionId, {
+      skills: result.exposed.map((skill) => skill.name),
+      sessionFile: input.sessionFile,
+      activeTools: result.activeTools,
+      attributions,
+    });
+    // 门禁②③（全局锁 / 总开关）与去抖在派发器里；这里必须同步返回，不 await
+    void dispatcher
+      .dispatch({
+        sessionId: input.sessionId,
+        skills: result.exposed.map((skill) => skill.name),
+        sessionFile: input.sessionFile,
+        attributions,
+      })
+      .then((outcome) => {
+        if (outcome.status === "skipped") log(`[skill-evolve] 本轮未派生：${outcome.why}`);
+        else if (outcome.status === "dispatched") observer.noteDispatched(outcome.run.runId);
+      })
+      .catch((error: unknown) => recordHandlerError("dispatch", error));
+  };
+
+  const recordHandlerError: Evolution["recordHandlerError"] = (where, error) => {
+    telemetry.append({ kind: "handler_error", where, message: String(error) });
+  };
+
+  const runNow: Evolution["runNow"] = async (input) => {
+    const remembered = lastRound.get(input.sessionId);
+    const outcome = await dispatcher.dispatch(
+      {
+        sessionId: input.sessionId,
+        skills: remembered?.skills ?? [],
+        sessionFile: input.sessionFile ?? remembered?.sessionFile,
+        attributions: remembered?.attributions,
+      },
+      { bypassThrottle: true, trigger: "manual" },
+    );
+    return renderManualDispatch(outcome);
+  };
+
+  const shutdown: Evolution["shutdown"] = () => {
+    try {
+      // 同步补发：主进程马上退出，await 很可能到此为止就没了
+      const dispatched = dispatcher.flushPending();
+      if (dispatched > 0) log(`[skill-evolve] 退出前补发 ${dispatched} 次复盘`);
+    } catch (error) {
+      log(`[skill-evolve] 退出补发失败：${String(error)}`);
+    }
+    void telemetry.flush().catch((error: unknown) => log(`[skill-evolve] 遥测刷盘失败：${String(error)}`));
+  };
+
+  const views = createViews({ evolutionDir, telemetryDir, config, now, mechanical, mechanicalReporter, baselineGate, modelTools });
+
+  const acceptBaseline = (mode: "accept" | "reset"): Promise<string> => (mode === "reset" ? baselineGate.reset() : baselineGate.acceptAll());
+
+  const setEnabled = async (on: boolean): Promise<string> => {
+    Object.assign(config, await saveConfigSwitch(evolutionDir, on, deps.queue));
+    return on
+      ? `技能进化已打开（采集 + 自动复盘）：${configFile(evolutionDir)}（当前会话立即生效）`
+      : `技能进化已全部关闭（采集也停）：${configFile(evolutionDir)}（当前会话立即生效）`;
+  };
+
+  /** 只切一个开关：另一个保持原值（`collect` = telemetry、`review` = enabled） */
+  const setFlag = async (field: ConfigFlag, value: boolean): Promise<string> => {
+    Object.assign(config, await saveFlag(evolutionDir, field, value, deps.queue));
+    return `${FLAG_LABEL[field]}已${value ? "开启" : "关闭"}：${configFile(evolutionDir)}（当前会话立即生效）\n${flagStateText(config.enabled, config.telemetry)}`;
+  };
+
+  return {
+    recordAdvertised,
+    noteToolCall,
+    resolveToolResult,
+    settle,
+    recordHandlerError,
+    runNow,
+    shutdown,
+    flush: () => telemetry.flush(),
+    statusText: views.statusText,
+    reportText: views.reportText,
+    auditText: views.auditText,
+    acceptBaseline,
+    setEnabled,
+    setFlag,
+    model: modelTools,
+    apply: applyTools,
+    observe: observer,
+  };
+}

package/extensions/skill-evolve/lib/flags.ts

@@ -0,0 +1,44 @@
+/**
+ * 「采集遥测」与「自动复盘」两个开关的口径：字段名、标签、后果说明、状态文案只此一份。
+ *
+ * 两个字段在配置里本来就是独立的（`telemetry` 只写本地 jsonl，不花 token；`enabled` 派生子进程复盘，花 token），
+ * 命令文案、Web 控制条、HTTP 的 `field` 校验都从这里取 —— 三处各写一份字符串，
+ * 迟早出现「命令里叫遥测、网页上叫采集、日志里又叫 telemetry」这种对不上的情况。
+ */
+import type { ConfigFlag } from "./config.ts";
+
+/** 字段顺序即界面顺序：先采集（不花钱的），再复盘（花钱的） */
+export const FLAG_FIELDS: readonly ConfigFlag[] = ["telemetry", "enabled"];
+
+export const FLAG_LABEL: Record<ConfigFlag, string> = { telemetry: "采集遥测", enabled: "自动复盘" };
+
+/** 后果说明：两个开关长得一样，不写清各自花什么，人只会以为都是「开关插件」 */
+export const FLAG_EFFECT: Record<ConfigFlag, string> = {
+  telemetry: "只写本地日志，不花 token",
+  enabled: "会派生子进程，花 token",
+};
+
+/** 命令名 → 字段：`collect` 管采集，`review` 管复盘（命令名与字段名故意不同，别在别处再映射一遍） */
+export const COMMAND_FLAG: Record<"collect" | "review", ConfigFlag> = {
+  collect: "telemetry",
+  review: "enabled",
+};
+
+/** 参数 → 字段：不认的值一律 null（调用方回用法提示或 400，不猜一个默认值） */
+export function parseFlag(value: string | null | undefined): ConfigFlag | null {
+  return value === "telemetry" || value === "enabled" ? value : null;
+}
+
+/** 一行两段的状态文案：`status` 与命令回执共用，免得同一句话在两处写法不同 */
+export function flagStateText(enabled: boolean, telemetry: boolean): string {
+  const collect = telemetry ? "采集：开（遥测写入 .pi/evolution/telemetry/）" : "采集：关（不写遥测）";
+  const review = enabled ? "复盘：开（会派生 agent）" : "复盘：关（不会派生 agent）";
+  return `${collect}｜${review}`;
+}
+
+/** 只开复盘却不采集时唯一的不一致组合：归因靠遥测，缺了就只能退到原始会话，加载率算不出来 */
+export const TELEMETRY_OFF_WARNING = "复盘在跑但采集关着：归因只能靠原始会话，加载率不可得";
+
+export function telemetryOffWhileEnabled(enabled: boolean, telemetry: boolean): boolean {
+  return enabled && !telemetry;
+}

package/extensions/skill-evolve/lib/gate0.ts

@@ -0,0 +1,78 @@
+/**
+ * 闸0 · 授权核对（设计稿 13.2）：会话开始时记一份 `.pi/skills` 的 git 摘要，采纳前重算。
+ *
+ * 判据只有一条：这段时间里 `.pi/skills` 的 git status / diff **一个字节都不能变**。
+ * 变了就说明有人（或另一个会话）也在改同一片文件 —— 这时写盘会把别人的改动一起提交，
+ * 所以本插件**不写盘**，只告警并留证据（03/06 里都有），绝不自动还原别人的改动：
+ * 并发编辑时「自动还原」= 直接把别人的活儿删掉。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { MutationQueue } from "./telemetry.ts";
+
+/** 同步跑 git 的注入点：测试给假实现，生产给 spawnSync 包装（绝不在测试里真起进程） */
+export type GitRunner = (args: string[], cwd: string) => { code: number; out: string };
+
+export interface Gate0Snapshot {
+  at: number;
+  status: string;
+  diff: string;
+  /** git 自身失败的说明（非空即视为无法核对） */
+  error?: string;
+}
+
+export const GATE0_FILE = "gate0.json";
+
+export function gate0Path(evolutionDir: string): string {
+  return path.join(evolutionDir, "locks", GATE0_FILE);
+}
+
+export function captureGate0(git: GitRunner, cwd: string, now: number): Gate0Snapshot {
+  const status = git(["status", "--porcelain", "--", ".pi/skills"], cwd);
+  const diff = git(["diff", "--", ".pi/skills"], cwd);
+  const failed: string[] = [];
+  if (status.code !== 0) failed.push(`status 退出码 ${status.code}`);
+  if (diff.code !== 0) failed.push(`diff 退出码 ${diff.code}`);
+  return {
+    at: now,
+    status: status.out,
+    diff: diff.out,
+    ...(failed.length > 0 ? { error: failed.join("；") } : {}),
+  };
+}
+
+/**
+ * 与采纳前的现场比对。返回 null = 未漂移；返回字符串 = 拒绝采纳的原因（人话）。
+ * 没有快照（扩展不是从 session_start 起来的）时按「无法核对」处理 —— 宁可拒采，不赌。
+ */
+export function gate0Drift(before: Gate0Snapshot | null, after: Gate0Snapshot): string {
+  if (!before) return "闸0：没有会话起点的 .pi/skills 快照，无法核对授权面";
+  if (after.error) return `闸0：git 不可用（${after.error}）`;
+  if (before.status !== after.status || before.diff !== after.diff) {
+    return "闸0：.pi/skills 在会话开始后被改动过（并发编辑），本次拒绝写盘并告警";
+  }
+  return "";
+}
+
+export async function saveGate0(evolutionDir: string, snapshot: Gate0Snapshot, queue: MutationQueue): Promise<void> {
+  const file = gate0Path(evolutionDir);
+  await queue(file, async () => {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+  });
+}
+
+export function readGate0(evolutionDir: string): Gate0Snapshot | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(gate0Path(evolutionDir), "utf8")) as Partial<Gate0Snapshot>;
+    if (typeof raw.status !== "string" || typeof raw.diff !== "string") return null;
+    return {
+      at: typeof raw.at === "number" ? raw.at : 0,
+      status: raw.status,
+      diff: raw.diff,
+      ...(typeof raw.error === "string" ? { error: raw.error } : {}),
+    };
+  } catch {
+    return null;
+  }
+}