pi-skill-evolve 0.1.9 → 0.1.11

package/extensions/skill-evolve/lib/web/done.ts

@@ -1,11 +1,11 @@
 /**
- * 「已处理」视图的数据：回滚 / 失败 / 否决 / 被取代这四种终态。
+ * 「已处理」视图的数据：回滚 / 失败 / 否决 / 被取代 / 评审失败 / 已放弃 / 越权写入这七种终态。
  *
  * 为什么不和「已采纳」混：采纳有自己的页（见 ./applied.ts），两边都收就等于两个 tab 各算一遍。
  * 队列记录会覆盖同一个 runId 的 run.json 版本：它有层级（auto/approval）与失败详情，比只有状态有用。
  */
 import type { QueueItem } from "../queue.ts";
-import type { RunSummary } from "../runs.ts";
+import type { RunStatus, RunSummary } from "../runs.ts";
 import { asNumber, asText } from "./json-read.ts";
 import { sessionForRun, sessionIndex, sessionOfRun, type SessionRef } from "./run-session.ts";
 
@@ -26,16 +26,30 @@ export interface DoneItem {
 }
 
 /**
- * 「已处理」收的终态：回滚 / 失败 / 否决 / 被取代。
+ * 「已处理」收的终态：回滚 / 失败 / 否决 / 被取代，以及过去漏收的评审失败 / 已放弃 / 越权写入。
  * **不含 applied** —— 采纳有自己的页（见 ./applied.ts），两边都收就等于两个 tab 都算一遍。
+ *
+ * 导出成数组是为了「状态覆盖性」测试（test/web-view-coverage.test.ts）：
+ * 新增一个 run 状态却没有任何视图收它，那类 run 会在面板上直接消失、只能翻目录 ——
+ * review_failed / abandoned / unauthorized_write 就是这么丢的，所以这个清单必须可被测试读取。
  */
-const DONE_STATUSES = new Set(["rolled-back", "failed", "rejected", "superseded"]);
+export const DONE_STATUSES: readonly RunStatus[] = [
+  "rolled-back",
+  "failed",
+  "rejected",
+  "superseded",
+  "review_failed",
+  "abandoned",
+  "unauthorized_write",
+];
+
+const DONE_STATUS_SET = new Set<string>(DONE_STATUSES);
 
 export function buildDone(items: readonly QueueItem[], runs: readonly RunSummary[], evolutionDir: string): DoneItem[] {
   const byRun = new Map<string, DoneItem>();
   const sessions = sessionIndex(runs);
   for (const run of runs) {
-    if (!DONE_STATUSES.has(run.status)) continue;
+    if (!DONE_STATUS_SET.has(run.status)) continue;
     byRun.set(run.runId, {
       runId: run.runId,
       status: run.status,
@@ -49,7 +63,7 @@ export function buildDone(items: readonly QueueItem[], runs: readonly RunSummary
   }
   // 队列记录覆盖同 runId：它有层级（auto/approval）与失败详情，比 run.json 只有状态有用
   for (const item of items) {
-    if (!DONE_STATUSES.has(item.status)) continue;
+    if (!DONE_STATUS_SET.has(item.status)) continue;
     byRun.set(item.runId, {
       runId: item.runId,
       status: item.status,

package/extensions/skill-evolve/lib/web/pending.ts

@@ -8,7 +8,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { QueueItem } from "../queue.ts";
-import type { RunSummary } from "../runs.ts";
+import type { RunStatus, RunSummary } from "../runs.ts";
 import { CHILD_LOG } from "../spawn-plan.ts";
 import { classifyStale, readLogTail, readRunError } from "../stale.ts";
 import type { WebStateDeps } from "./data.ts";
@@ -30,6 +30,12 @@ function defaultAlive(pid: number): boolean {
 /** 待处理五来源：正在跑 / 已判卡死 / 队列待批 / 已出结论等评审 / 评审通过等入队 */
 export type PendingKind = "running" | "approval" | "stale" | "to-review" | "reviewed";
 
+/**
+ * 待处理页收的 run 状态（导出给 test/web-view-coverage.test.ts 做状态覆盖性检查）。
+ * running 的判据是 dispatched + pid 还活着，所以 dispatched 算这里收；reviewed 是「等入队」。
+ */
+export const PENDING_RUN_STATUSES: readonly RunStatus[] = ["dispatched", "analyzed", "proposed", "reviewed", "stale"];
+
 export interface PendingItem {
   runId: string;
   kind: PendingKind;

package/extensions/skill-evolve/lib/web/render-rows.ts

@@ -123,13 +123,22 @@ export function pendingRows(items: readonly PendingItem[], ctx: RowContext): Lis
   }));
 }
 
-/** 已处理：终态各一色；被拒绝是暗红（是结论，不是故障），失败才是红 */
+/** 已处理：终态各一色；被拒绝是暗红（是结论，不是故障），失败才标题红色
+ * 键必须与 run.json / 队列里的 status 一字不差：抄错一个字符（比如 rolledback）徽章就永远匹配不上，
+ * 页面上会回落到淡灰 + 原始英文，而不是中文文案。 */
 export function doneRows(items: readonly DoneItem[]): ListRow[] {
   const tone: Record<string, { text: string; tone: BadgeTone }> = {
     applied: { text: "已采纳", tone: "green" },
     rejected: { text: "已拒绝", tone: "darkred" },
     failed: { text: "失败", tone: "red" },
-    rolledback: { text: "已回滚", tone: "faint" },
+    "rolled-back": { text: "已回滚", tone: "faint" },
+    superseded: { text: "已被取代", tone: "faint" },
+    // 评审器自己出问题：是故障，不是结论，所以给红（同 failed），不给暗红
+    review_failed: { text: "评审失败", tone: "red" },
+    // 提案者没下文 / 放弃：没发生坏事，用淡灰
+    abandoned: { text: "已放弃", tone: "faint" },
+    // 越权写入是纪律事故，必须红
+    unauthorized_write: { text: "越权写入", tone: "red" },
   };
   return items.map((item) => ({
     runId: item.runId,

package/extensions/skill-evolve/lib/web/render-run.ts

@@ -8,7 +8,7 @@
  */
 import type { WebState } from "./data.ts";
 import { DIFF_PREVIEW_LINES, renderDiffLines, parseDiffLines } from "./diff-lines.ts";
-import type { RunBlocking, RunDetail } from "./run-detail.ts";
+import type { RunBlocking, RunDetail, RunPassing } from "./run-detail.ts";
 import { sessionHref } from "./run-session.ts";
 import { shellPage } from "./shell.ts";
 import { escapeHtml, formatStamp } from "./text.ts";
@@ -89,20 +89,42 @@ function candidateSection(detail: RunDetail): string {
 </section>`;
 }
 
-function blockingRows(blocking: readonly RunBlocking[]): string {
-  if (blocking.length === 0) return `<p class="hint">blocking：0 条。</p>`;
-  const rows = blocking.map((item) => {
-    const where = item.file.length > 0 ? `${item.file}${item.line === null ? "" : `:${item.line}`}` : "（未写位置）";
-    return `<tr><td>${escapeHtml(item.issue)}</td><td><code>${escapeHtml(where)}</code></td><td>${escapeHtml(item.quote)}</td></tr>`;
+/** 旧 run 的兼容文案：03-review.json 没有 summary / passed 时明说「不是页面坏了」 */
+const LEGACY_REVIEW_NOTE = "该 run 由旧版评审产出，没有结论摘要（重跑一次就有）";
+/** 新版评审也确实可能两块全空（比如 skipped）：那时不能说「旧版」，要说「没给理由」 */
+const NO_REASON_NOTE = "03-review.json 里没有 blocking / passed：这一轮评审只写了结论，没写理由。";
+
+/** 理由表的一行：blocking 用 issue、passed 用 point，但三列形状一样（说明 / 证据位置 / 原文引用） */
+interface ReasonRow {
+  text: string;
+  file: string;
+  line: number | null;
+  quote: string;
+}
+
+function reasonTable(head: string, rows: readonly ReasonRow[]): string {
+  if (rows.length === 0) return "";
+  const body = rows.map((row) => {
+    const where = row.file.length > 0 ? `${row.file}${row.line === null ? "" : `:${row.line}`}` : "（未写位置）";
+    return `<tr><td>${escapeHtml(row.text)}</td><td><code>${escapeHtml(where)}</code></td><td>${escapeHtml(row.quote)}</td></tr>`;
   });
-  return `<table class="tbl">
-<thead><tr><th>问题</th><th>证据位置</th><th>原文引用</th></tr></thead>
+  return `<h3>${head}</h3>
+<table class="tbl">
+<thead><tr><th>${head === "阻断意见" ? "问题" : "通过点"}</th><th>证据位置</th><th>原文引用</th></tr></thead>
 <tbody>
-${rows.join("\n")}
+${body.join("\n")}
 </tbody>
 </table>`;
 }
 
+function blockingRows(blocking: readonly RunBlocking[]): ReasonRow[] {
+  return blocking.map((item) => ({ text: item.issue, file: item.file, line: item.line, quote: item.quote }));
+}
+
+function passedRows(passed: readonly RunPassing[]): ReasonRow[] {
+  return passed.map((item) => ({ text: item.point, file: item.file, line: item.line, quote: item.quote }));
+}
+
 function reviewSection(detail: RunDetail): string {
   if (detail.review === null) {
     return `<section>
@@ -111,6 +133,17 @@ function reviewSection(detail: RunDetail): string {
 </section>`;
   }
   const review = detail.review;
+  // 结论摘要：用户问的第一句永远是「为什么」，所以它排在 verdict 那一行之后、理由表之前，且字号大一档
+  // legacy 看的是 03-review.json 里有没有新契约的键，不是「summary 空不空」：
+  // 新版评审失败时同样没有 summary，那时要说「没给理由」，不能说成旧版
+  const legacy = review.legacy;
+  const summary = legacy
+    ? `<p class="hint">${LEGACY_REVIEW_NOTE}</p>`
+    : `<p class="verdict-summary">${escapeHtml(review.summary ?? "")}</p>`;
+  const blocked = reasonTable("阻断意见", blockingRows(detail.blocking));
+  const passed = reasonTable("通过理由", passedRows(detail.passed));
+  // 旧 run 已经有上面那句兼容文案了，不再叠一句「没给理由」
+  const emptyNote = !legacy && blocked === "" && passed === "" ? `<p class="hint">${NO_REASON_NOTE}</p>` : "";
   return `<section>
 <h2>评审结论</h2>
 <p class="kv-line">
@@ -119,7 +152,10 @@ action <b>${escapeHtml(review.action)}</b> ·
 状态 ${escapeHtml(review.status)} ·
 评审模型 <code>${escapeHtml(review.reviewerModel)}</code>
 </p>
-${blockingRows(detail.blocking)}
+${summary}
+${emptyNote}
+${blocked}
+${passed}
 </section>`;
 }
 

package/extensions/skill-evolve/lib/web/reports.ts

@@ -5,7 +5,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { readVerify } from "../apply.ts";
-import type { RunSummary } from "../runs.ts";
+import type { RunStatus, RunSummary } from "../runs.ts";
 import { readRunError } from "../stale.ts";
 import { asNumber, asRecord, asText, readJson, reasonLabel } from "./json-read.ts";
 import { sessionFromRecord, type SessionRef } from "./run-session.ts";
@@ -13,6 +13,12 @@ import { sessionFromRecord, type SessionRef } from "./run-session.ts";
 /** 单条报告里最多列几个技能：全量列会把 details 撑成第二份 findings */
 export const MAX_FINDING_ROWS = 5;
 
+/**
+ * 复盘报告页唯一由 run 状态决定的分支：status=stale 且没有 findings 的失败 run 也要占一行。
+ * （其余 run 靠「能读到 01-findings.json」入场，与状态无关）导出给覆盖性测试用。
+ */
+export const REPORTS_RUN_STATUSES: readonly RunStatus[] = ["stale"];
+
 export interface FindingRow {
   skill: string;
   kind: string;
@@ -126,13 +132,15 @@ export function buildReports(evolutionDir: string, runs: readonly RunSummary[]):
       // 失败也要有一行档案：每条 run 都能在报告里找到，不能因为没产出就从历史里消失
       const summary = summaries.get(runId);
       const raw = readJson<Record<string, unknown>>(path.join(runDir, "run.json"));
-      if ((summary?.status ?? asText(raw?.status)) !== "stale") continue;
+      const status = summary?.status ?? asText(raw?.status);
+      // 判据用清单本体而不是写死 "stale"：清单改了代码就跟着改（同类写法见 ./applied.ts）
+      if (!REPORTS_RUN_STATUSES.some((known) => known === status)) continue;
       const error = readRunError(runDir);
       const tail = error?.childLogTail ?? [];
       const lastLine = tail.length > 0 ? tail[tail.length - 1]!.trim() : "";
       reports.push({
         runId,
-        status: "stale",
+        status,
         trigger: meta.trigger,
         session: meta.session,
         startedAt: summary?.dispatchedAt ?? asNumber(raw?.dispatchedAt),

package/extensions/skill-evolve/lib/web/run-detail.ts

@@ -33,6 +33,14 @@ export interface RunBlocking {
   quote: string;
 }
 
+/** 通过理由（03-review.json 的 passed）：哪一点没问题 + 支撑它的原文 */
+export interface RunPassing {
+  point: string;
+  file: string;
+  line: number | null;
+  quote: string;
+}
+
 export interface RunGate {
   gate: string;
   name: string;
@@ -70,8 +78,18 @@ export interface RunDetail {
   /** candidate 目录里的技能名（与 skill 一致才读全文） */
   candidateSkill: string | null;
   candidateText: string | null;
-  review: { status: string; verdict: string; action: string; reviewerModel: string } | null;
+  review: {
+    status: string;
+    verdict: string;
+    action: string;
+    reviewerModel: string;
+    summary: string | null;
+    /** 03-review.json 里连 summary / passed 两个键都没有 = v0.1.9 之前写的记录（详情页要说旧版，而不是说「没给理由」） */
+    legacy: boolean;
+  } | null;
   blocking: RunBlocking[];
+  /** 通过理由：旧 run 没有这个字段，读出来是空数组 */
+  passed: RunPassing[];
   gates: RunGate[];
   verifyStatus: string | null;
   findings: RunFinding[];
@@ -95,30 +113,40 @@ function exists(file: string): boolean {
   }
 }
 
-/** 03-review.json → verdict / action / reviewerModel + blocking（每条带 file:line 与原文引用） */
-function readReview(runDir: string): Pick<RunDetail, "review" | "blocking"> {
-  const raw = asRecord(readJson<unknown>(path.join(runDir, "03-review.json")));
-  if (!raw) return { review: null, blocking: [] };
-  const blocking: RunBlocking[] = [];
-  for (const item of Array.isArray(raw.blocking) ? raw.blocking : []) {
+/** 03-review.json 里的证据项 → 行上的 file / line / quote（blocking 与 passed 共用同一形状） */
+function readEvidenceRows<T>(items: unknown, build: (text: string, file: string, line: number | null, quote: string) => T): T[] {
+  const rows: T[] = [];
+  for (const item of Array.isArray(items) ? items : []) {
     const record = asRecord(item);
     if (!record) continue;
     const evidence = asRecord(record.evidence);
-    blocking.push({
-      issue: asText(record.issue, "（未写问题描述）"),
-      file: asText(evidence?.file),
-      line: asNumber(evidence?.line),
-      quote: asText(evidence?.quote),
-    });
+    const text = asText(record.issue) || asText(record.point) || "（未写说明）";
+    rows.push(build(text, asText(evidence?.file), asNumber(evidence?.line), asText(evidence?.quote)));
   }
+  return rows;
+}
+
+/**
+ * 03-review.json → verdict / action / reviewerModel / summary + blocking + passed。
+ * 旧版评审产出的文件没有 summary / passed：summary 读成 null、passed 读成空数组（不抛、不补造）。
+ */
+function readReview(runDir: string): Pick<RunDetail, "review" | "blocking" | "passed"> {
+  const raw = asRecord(readJson<unknown>(path.join(runDir, "03-review.json")));
+  if (!raw) return { review: null, blocking: [], passed: [] };
+  const blocking = readEvidenceRows<RunBlocking>(raw.blocking, (issue, file, line, quote) => ({ issue, file, line, quote }));
+  const passed = readEvidenceRows<RunPassing>(raw.passed, (point, file, line, quote) => ({ point, file, line, quote }));
   return {
     review: {
       status: asText(raw.status, "（未写状态）"),
       verdict: asText(raw.verdict, "（未写 verdict）"),
       action: asText(raw.action, "（未写 action）"),
       reviewerModel: asText(raw.reviewerModel, "（未写模型）"),
+      summary: asText(raw.summary, "") || null,
+      // 两个键都不存在才算旧记录：新版即使评审失败也会写 passed: []（空数组也是一个键），不能混谈
+      legacy: raw.summary === undefined && raw.passed === undefined,
     },
     blocking,
+    passed,
   };
 }
 

package/extensions/skill-evolve/lib/web/style.ts

@@ -113,6 +113,8 @@ a.btn { display: inline-block; color: var(--blue); padding: 1px 8px; border: 1px
 .kv .k { color: var(--muted); font-size: 12px }
 .kv .v { color: var(--fg) }
 .kv-line { margin: 4px 0 }
+/* 评审结论摘要：详情页里唯一「大一号」的正文，用户上来先读这一句 */
+.verdict-summary { margin: 6px 0; font-size: 15px; font-weight: 600; color: var(--fg) }
 a.run { color: #c8d3e6; border-bottom: 1px dashed #45505f }
 a.run:hover { border-bottom-color: var(--blue); text-decoration: none }
 a.sess { color: var(--muted); border-bottom: 1px dashed #45505f }

package/extensions/skill-evolve/test/dispatch.test.ts

@@ -132,6 +132,17 @@ test("纯函数：pi 路径优先级、runId 形态、去抖判据", () => {
   assert.equal(shouldDebounce(NOW - 90_000, NOW, 90_000), false);
 });
 
+test("纯函数：pi 路径在陌生机器上也解得出来（不写死别人的家目录）", () => {
+  // 2026-11-09 事故回归：常量必须跟当前用户 home 走，且 home 不存在时退到 PATH
+  assert.equal(DEFAULT_PI_BIN, path.join(os.homedir(), ".pi", "agent", "bin", "pi"));
+  const none = (): boolean => false;
+  assert.equal(resolvePiBin({}, { exists: none }), DEFAULT_PI_BIN);
+  const onPath = path.join("/opt/node/bin", "pi");
+  assert.equal(resolvePiBin({ PATH: ["/x", path.dirname(onPath)].join(path.delimiter) }, { exists: (p) => p === onPath }), onPath);
+  // home 下的优先于 PATH
+  assert.equal(resolvePiBin({ PATH: path.dirname(onPath) }, { exists: () => true }), DEFAULT_PI_BIN);
+});
+
 test("buildPrompt：带会话原文/索引/run 目录，并写清覆盖轮数", () => {
   const full = buildPrompt({ template: "模板", sessionFile: "/s.jsonl", indexFile: "/i.json", runDir: "/r", sessionId: "s1", skills: ["a", "b"], dispatchedAt: NOW });
   assert.equal(full.includes("会话原文：/s.jsonl"), true);

package/extensions/skill-evolve/test/review-post.test.ts

@@ -1,21 +1,27 @@
 /**
  * 评审后处理单测（设计稿 12.3）：结构、证据、一致性一律代码判，不信 LLM 自觉。
  * 每条用例对应「模型输出的一种坏法」，覆盖判 invalid / reject 的每一道关。
+ * 「结论必须写为什么」也在这里钉住：没有 summary、pass 却没有 passed（或 reject 却没有 blocking）一律 invalid。
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { parseReviewJson, postProcessReview } from "../lib/review-post.ts";
+import { parseReviewJson, postProcessReview, SUMMARY_MAX } from "../lib/review-post.ts";
 
-const GOOD_PASS = JSON.stringify({ verdict: "pass", blocking: [], notes: "没问题" });
-const withBlocking = (verdict: string, evidence: unknown): string =>
-  JSON.stringify({ verdict, blocking: [{ issue: "有问题", evidence }], notes: "" });
+const SUMMARY = "新描述补了触发场景词，没删原有禁令";
 const EVIDENCE = { file: ".pi/skills/demo/SKILL.md", line: 12, quote: "允许用 find" };
+const PASSED = [{ point: "原有禁止项仍完整保留", evidence: EVIDENCE }];
+const GOOD_PASS = JSON.stringify({ verdict: "pass", summary: SUMMARY, blocking: [], passed: PASSED, notes: "没问题" });
+const withBlocking = (verdict: string, evidence: unknown): string =>
+  JSON.stringify({ verdict, summary: SUMMARY, blocking: [{ issue: "有问题", evidence }], passed: [], notes: "" });
 
-test("合法 pass 返回 ok", () => {
+test("合法 pass 返回 ok，且 summary / passed 原样带出", () => {
   const result = postProcessReview(GOOD_PASS);
   assert.equal(result.status, "ok");
   assert.equal(result.verdict, "pass");
   assert.deepEqual(result.blocking, []);
+  assert.equal(result.summary, SUMMARY);
+  assert.equal(result.passed.length, 1);
+  assert.equal(result.passed[0].point, "原有禁止项仍完整保留");
 });
 
 test("带 ```json 围栏与前后废话也能抠出 JSON", () => {
@@ -71,11 +77,52 @@ test("pass 却带 blocking 判 invalid：contradiction", () => {
 });
 
 test("reject 带完整证据返回 ok 且保留 blocking/notes", () => {
-  const result = postProcessReview(JSON.stringify({ verdict: "reject", blocking: [{ issue: "引入 find", evidence: EVIDENCE }], notes: "违反 P0" }));
+  const text = JSON.stringify({ verdict: "reject", summary: SUMMARY, blocking: [{ issue: "引入 find", evidence: EVIDENCE }], notes: "违反 P0" });
+  const result = postProcessReview(text);
   assert.equal(result.status, "ok");
   assert.equal(result.verdict, "reject");
   assert.equal(result.blocking[0].evidence.line, 12);
   assert.equal(result.notes, "违反 P0");
+  assert.equal(result.summary, SUMMARY);
+  assert.deepEqual(result.passed, [], "reject 时没给 passed 就是空数组，不补造");
+});
+
+test("pass 但没有 passed（只写「通过」两个字）判 invalid：missing-passed", () => {
+  const text = JSON.stringify({ verdict: "pass", summary: SUMMARY, blocking: [] });
+  const result = postProcessReview(text);
+  assert.equal(result.status, "invalid");
+  assert.match(result.detail ?? "", /missing-passed/);
+});
+
+test("reject / revise 但没有 blocking 判 invalid：missing-blocking", () => {
+  for (const verdict of ["reject", "revise"]) {
+    const result = postProcessReview(JSON.stringify({ verdict, summary: SUMMARY, blocking: [] }));
+    assert.equal(result.status, "invalid", verdict);
+    assert.match(result.detail ?? "", /missing-blocking/);
+  }
+});
+
+test("passed 项也要有 point 与证据：缺了就是 missing-evidence", () => {
+  const noEvidence = postProcessReview(JSON.stringify({ verdict: "pass", summary: SUMMARY, blocking: [], passed: [{ point: "没问题" }] }));
+  assert.equal(noEvidence.status, "invalid");
+  assert.match(noEvidence.detail ?? "", /missing-evidence: passed/);
+  assert.match(noEvidence.detail ?? "", /evidence 不是对象/);
+});
+
+test("没写 summary（缺字段 / 空串 / 非字符串）判 invalid：bad-summary", () => {
+  for (const summary of [undefined, "", "   ", 42]) {
+    const result = postProcessReview(JSON.stringify({ verdict: "pass", summary, blocking: [], passed: PASSED }));
+    assert.equal(result.status, "invalid", `summary=${String(summary)}`);
+    assert.match(result.detail ?? "", /bad-summary/);
+  }
+});
+
+test(`summary 超 ${SUMMARY_MAX} 字按上限截断（含省略号不超过 ${SUMMARY_MAX}），不判 invalid`, () => {
+  const long = "因为".repeat(60);
+  const result = postProcessReview(JSON.stringify({ verdict: "pass", summary: long, blocking: [], passed: PASSED }));
+  assert.equal(result.status, "ok");
+  assert.equal(result.summary?.length, SUMMARY_MAX);
+  assert.ok(result.summary?.endsWith("…"), "截断要留省略号，让人知道后面还有话");
 });
 
 test("机械复验失败一票 reject，覆盖 LLM 的 pass", () => {

package/extensions/skill-evolve/test/review-prompt.test.ts

@@ -103,3 +103,12 @@ test("verdict 语义写进 prompt：能改的小毛病不许判 reject（真实
   assert.match(prompt, /revise：方向可以接受/);
   assert.match(prompt, /reject：删掉了原有的明确禁止项/);
 });
+
+test("输出契约要求写「为什么」：summary 必填 + pass 必须给 passed", () => {
+  const prompt = buildReviewPrompt({ skillName: "demo", skillText: "正文", diffApplied: true, diff: "+++ b/x\n", hardRules: [] });
+  assert.match(prompt, /"summary":"一句话结论（≤80 字，必须写清因为什么）"/);
+  assert.match(prompt, /"passed":\[\{"point"/);
+  assert.match(prompt, /summary 必填/);
+  assert.match(prompt, /verdict=pass 时 blocking=\[\] 且 passed 至少 1 条/);
+  assert.match(prompt, /verdict=reject\/revise 时 blocking 至少 1 条/);
+});

package/extensions/skill-evolve/test/review-record.test.ts

@@ -0,0 +1,59 @@
+/**
+ * 评审记录落盘形态的单测：`03-review.md` 必须写出「为什么」（summary + 通过理由），
+ * 且 v0.1.9 之前的老记录（没有 summary / passed 字段）读进来也不能抛。
+ *
+ * 单独一份测试是因为 review-record.ts 全是纯函数；落盘字段与服务端回写由
+ * test/review-supervisor.test.ts 覆盖，细节页读取由 test/web-run-detail.test.ts 覆盖。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { renderReviewMarkdown, type ReviewRecord } from "../lib/review-record.ts";
+
+const EVIDENCE = { file: ".pi/skills/demo/SKILL.md", line: 3, quote: "description: 检索日志用 rg" };
+
+function record(extra: Partial<ReviewRecord> = {}): ReviewRecord {
+  return {
+    status: "rejected",
+    verdict: "revise",
+    blocking: [{ issue: "描述承诺大于正文", evidence: EVIDENCE }],
+    reviewerModel: "deepseek/deepseek-flash",
+    proposerModel: "deepseek/deepseek-flash",
+    sameModel: false,
+    action: "forbidden",
+    reviewedAt: 1794134158913,
+    reviewedAtIso: "2026-11-08T10:35:58.913Z",
+    ...extra,
+  };
+}
+
+test("03-review.md：summary 紧跟在标题后，blocking 与 passed 各成一段", () => {
+  const md = renderReviewMarkdown(
+    record({
+      summary: "描述承诺了正文没有的能力，其余约束未被破坏",
+      passed: [{ point: "原有禁令仍完整保留", evidence: { ...EVIDENCE, line: 9, quote: "一律用 rg" } }],
+    }),
+    "demo",
+  );
+  const lines = md.split("\n");
+  assert.equal(lines[0], "# 评审结论：revise");
+  assert.equal(lines[2], "**描述承诺了正文没有的能力，其余约束未被破坏**", "摘要要排在元信息之前");
+  assert.match(md, /## blocking\n\n- 描述承诺大于正文\n {2}- 证据：\.pi\/skills\/demo\/SKILL\.md:3 「description: 检索日志用 rg」/);
+  assert.match(md, /## passed\n\n- 原有禁令仍完整保留\n {2}- 证据：\.pi\/skills\/demo\/SKILL\.md:9 「一律用 rg」/);
+});
+
+test("03-review.md：老记录（没有 summary / passed）不抛，也不渲染空段", () => {
+  const md = renderReviewMarkdown(record(), "demo");
+  assert.equal(md.includes("## passed"), false, "没有通过理由就别留空段");
+  assert.equal(md.includes("**"), false, "没有摘要就没有加粗行（同模型警告是 > 开头，不受影响）");
+  assert.match(md, /## blocking/);
+});
+
+test("03-review.md：pass 且没有 blocking 时写「blocking：无」，通过理由照常列出", () => {
+  const md = renderReviewMarkdown(
+    record({ status: "reviewed", verdict: "pass", action: "auto", blocking: [], summary: "只给 description 补了触发词", passed: [{ point: "原有禁令仍在", evidence: EVIDENCE }] }),
+    "demo",
+  );
+  assert.match(md, /blocking：无/);
+  assert.match(md, /## passed/);
+  assert.equal(md.includes("## blocking"), false);
+});

package/extensions/skill-evolve/test/review-supervisor.test.ts

@@ -21,7 +21,14 @@ const DESC_DIFF = [
   "-description: 旧描述",
   "+description: 检索日志时用 rg，禁止 find 全盘扫",
 ].join("\n");
-const PASS = JSON.stringify({ verdict: "pass", blocking: [], notes: "没问题" });
+const EVIDENCE_ROW = { file: ".pi/skills/demo/SKILL.md", line: 4, quote: "description: 检索日志时用 rg，禁止 find 全盘扫" };
+const PASS = JSON.stringify({
+  verdict: "pass",
+  summary: "新描述只补了触发场景词，没删原有禁令",
+  blocking: [],
+  passed: [{ point: "原有禁止项仍在正文里", evidence: EVIDENCE_ROW }],
+  notes: "没问题",
+});
 const RUN_JSON = JSON.stringify({ runId: "run-1", status: "dispatched", cwd: "/repo", stages: [{ name: "analyze", model: "deepseek/flash", usage: {}, ms: 10 }] });
 /** 只放一条与仓库同形的 rg-over-find：用例不依赖 .pi/evolution/rules 文件是否在场 */
 const RULES = compileRules({
@@ -74,11 +81,18 @@ test("正常路径：pass → reviewed，写 03-review.json/.md 并回写 run.js
   assert.equal(review.proposerModel, "deepseek/flash");
   assert.equal(review.sameModel, true);
   assert.equal(review.action, "auto");
+  // 结论要能解释「为什么」：summary 与 passed 都得落盘（面板详情页读的就是这两个字段）
+  assert.equal(review.summary, "新描述只补了触发场景词，没删原有禁令");
+  assert.equal((review.passed as unknown[]).length, 1);
   const md = fs.text(`${RUN_DIR}/03-review.md`) ?? "";
   assert.ok(md.startsWith("> 同模型自评"), "同模型自评警告必须在首行");
+  assert.match(md, /\*\*新描述只补了触发场景词，没删原有禁令\*\*/);
+  assert.match(md, /## passed/);
   const run = fs.json(`${RUN_DIR}/run.json`) as Record<string, unknown>;
   assert.equal(run.status, "reviewed");
   assert.deepEqual((run.review as Record<string, unknown>).sameModel, true);
+  assert.equal((run.review as Record<string, unknown>).summary, "新描述只补了触发场景词，没删原有禁令");
+  assert.equal((run.review as Record<string, unknown>).passed, 1);
   assert.equal(prompts.length, 0);
 });