npm - @prismer/runtime - Versions diffs - 2.0.7 → 2.2.55 - Mend

@prismer/runtime 2.0.7 → 2.2.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (291) hide show

package/apc/skills/code-review/SKILL.md ADDED Viewed

@@ -0,0 +1,198 @@
+---
+name: code-review
+description: Review a diff against its acceptance criteria in four segments (convention adherence, bug scan, historical-context regressions, test-coverage gaps) as a NON-implementing agent. Findings are sorted by severity, each with file:line + a failure scenario. A planted defect must be caught; a clean diff must not be over-reported.
+license: MIT
+scope: coding
+compatibility:
+  - claude-code
+allowed-tools:
+  - Bash
+metadata:
+  category: review
+---
+# code-review
+对一个 **diff + 验收标准**做**四段评审**，产出按严重度排序的 findings（每条带 `file:line` + 失败场景），把 `/review` 的纪律移植到任意 coding agent（`apc/05` §2 S5 · `apc/12` code-review 行）。
+**什么时候用**：一个 coding task 改完、进 review 门时，需要由**非实施者**独立审这份 diff。
+## 评审独立性（第一铁律，P2-17）
+**评审必须由非实施 agent 执行**——实施者不自评自的 diff，与 no-self-approval 同精神（`apc/05` §2 评审独立性）。服务端也有牙：`code-review` 工件若 `reviewerId === task.assigneeId` 直接 403（`task-review-artifact.service.ts:126` `forbidden_implementer_self_review`）。
+开审**第一步**先自证独立：
+```bash
+git log --format='%an <%ae> %H' <base>..<head>    # 被审提交的作者
+# 断言：作者 ∉ {你自己}。若你就是作者 → 停手，报告"不能自评"，让另一个 agent 审。
+```
+## 四段评审（缺一段不算完）
+移植自 `/review` 的分段纪律——每段独立扫一个维度，产出 findings 再合并按严重度排序：
+| 段 | 扫什么 | 怎么做 | 典型 finding |
+| --- | --- | --- | --- |
+| **1. 规约符合** | diff 是否违反 CLAUDE.md / 既有约定 | 读根 + 相关目录的 CLAUDE.md，逐条对 diff | 用了被禁的 pattern、破坏 layer rules |
+| **2. bug 浅扫** | 只看 diff 本身的明显 bug | 读 `git diff`，聚焦大 bug（空/边界/错误分支/资源泄漏/并发），**不纠 lint/类型/格式**（CI 会管） | off-by-one、未处理的 null、错误吞异常 |
+| **3. 历史上下文** | 结合被改代码的历史看回归 | `git blame` / `git log -p` 被改的行，看这段代码为何这么写、这次改会不会破坏原意图 | 改动撤销了一个之前修 bug 的提交、重新引入已知回归 |
+| **4. 测试覆盖缺口** | 改动引入的行为有没有测试护 | `rg` 找对应测试文件、看新增/改动路径是否被断言 | 新分支零测试、负控缺失、断言放松 |
+**只标真问题，不纠鸡毛**（`/review` 纪律）：预存 bug、非本次改动行、CI 会抓的（lint/类型/格式/import）、senior 不会提的吹毛求疵——都不进 findings。这是**避免虚报**的纪律，直接对应负控"干净 diff 不虚报"。
+## Procedure
+### 1. 独立性自证（见上）— 不过则停手
+### 2. 取 diff + 验收标准
+```bash
+git diff <base>..<head> > /tmp/review.diff        # 或对 working tree: git diff
+cloud task acceptance "$PRISMER_TASK_ID"           # 读该 task 的验收标准（可选，若挂 task）
+```
+### 3. 四段逐段扫，每段产 findings
+每条 finding 的形状（缺一项不算数）：
+```
+{ severity: blocker|major|minor,
+  segment: convention|bug|history|coverage,
+  file: "src/foo.ts", line: 42,
+  finding: "<一句话说清是什么问题>",
+  failureScenario: "<在什么输入/时序下它会真的坏，可复现的因果>" }
+```
+**`failureScenario` 是承重字段**：说不清"怎么坏"的 = 还没验证的猜测，降级成 openQuestion，不当 finding 报。
+### 4. 合并 + 按严重度排序
+blocker → major → minor。产出：
+- `findings[]`（排序后）
+- `changeSummary`（这份 diff 干了什么，一段话）
+- `openQuestions[]`（拿不准的，不是 finding）
+- `residualTestGaps[]`（第 4 段发现的、本次不补但要记的覆盖缺口）
+### 5. 上报 criterion（挂 task 时）
+四段评审产物可作为结构化 review artifact 上报（服务端 schema `code-review`：要求 `findings[] / openQuestions[] / changeSummary / residualTestGaps[]`）：
+```bash
+# 写 artifact JSON（形状见上）到文件
+cat > /tmp/review-artifact.json <<'JSON'
+{ "findings": [...], "openQuestions": [...], "changeSummary": "...", "residualTestGaps": [...] }
+JSON
+# 有 blocker → failed；无 blocker → passed
+cloud task verify-criterion "$PRISMER_TASK_ID" "<criterion-id>" \
+  --outcome failed --review-artifact /tmp/review-artifact.json \
+  --note "1 blocker: src/foo.ts:42 unhandled null → NPE on empty input"
+```
+`--outcome` 合法值恰好四个：`passed | failed | n/a | waived`。**注意**：`verify-criterion` 的 review-artifact 走服务端 `reviewerId` = 调用凭据身份，若你的凭据解析成 assignee，服务端会 403（自评拦截）——这正是独立性的第二道门。
+## 输出契约（机器判据按这个复验，别自由发挥格式）
+本 skill 的验收判据不是「报告里出现了 `foo.ts:42` 这种形状」——旧判据 `[\w./-]+\.(ts|tsx|js):\d+` 正是这么写的，**随手编一个路径行号就能拿满分**。现在判据把报告里的每条 `file:line` **读回磁盘复核**（`structured-criteria.ts` 的 `cited-evidence`）。所以报告必须带下面两样**可机器解析**的东西——形状对但内容假的报告会被当场判红。
+**① 评审锚点声明**（一行；符号会被复核确实出现在该文件里）：
+```
+CHANGE-POINT: <被审的符号/表名/端点> @ <path>
+```
+**② findings 表**（markdown 表，**首列是 `file:line`**，按严重度排序）：判据逐行把 `file:line` 读回磁盘——**文件不存在 / 行号越界 / 该行是空行**，任意一条就判红；并且至少 2 条引用**所在的那一行必须真的含锚点符号**（"真实存在的行" ≠ "真实的搜索命中"）。
+```
+| file:line | severity | segment | finding | failureScenario |
+| --- | --- | --- | --- | --- |
+| src/lib/orphan-vacuum.ts:131 | blocker | bug | 空父集下 NOT IN 判 TRUE | im_tasks 清空后 vacuum 删掉合法审计行 |
+```
+**行号照抄 `rg -n` 的真实输出，不许凭印象写。** 说不清 `failureScenario` 的降级成 `openQuestion`，别塞进 findings 表凑行数。
+**③ 四段 keyed 行**（四段各占**独立一行**，key 逐字如下）：旧判据是「全文里出现过 convention/bug/history/coverage 这四组词」的 lookahead——**一篇编造的报告照样满分**，而且**整段跳过**也照绿（只要正文里恰好提到那个词）。现在判据（`dimension-coverage`）只认**这条 keyed 行**：某段没写这一行 = 该段**缺失判红**，正文里出现那个词**不算数**。每段的答案必须是**这一段真的看过的** `path:line`（读回磁盘复核），或者显式 `N/A — <理由≥20 非空白字符>`：
+**每段必须以一个 verdict token 开头**（`covered` = 该段审过且没问题 / `gap` = 该段发现了问题 / `N/A — <理由≥20 字符>` = 该段不适用），然后才是 `path:line`：
+```
+- SEGMENT-convention: covered | src/im/sql/528_task_log_nullable_taskid_for_ops_audit.sql:1 | 编号无缺口、双 schema 同步
+- SEGMENT-bug: gap | src/lib/orphan-vacuum.ts:131 | 空父集下 NOT IN 判 TRUE，删掉合法审计行
+- SEGMENT-history: covered | src/im/sql/528_task_log_nullable_taskid_for_ops_audit.sql:13 | 描述符自 177773e9 起未随列语义更新
+- SEGMENT-coverage: N/A — `rg -l` 在本改动面上零测试文件命中，本段没有可审的测试面（缺口本身记进 residualTestGaps）
+```
+> **⚠️ `SEGMENT-bug` 在本 sample task 上被钉死为 `gap`**（判据 arg `requiredVerdicts`）。原因是实测出来的：一份**明确写着「未发现 blocker 级问题，建议合入」、还主动复述那条错误安全性断言**的评审，在加这条之前拿 **6/6 满分**——因为旧判据「the real defect surfaced」是一串宽泛关键词（`vacuum` / `删除` / `delete` / `审计行`），而**这个 diff 的主题本身就是 orphan-vacuum 和审计行**，任何谈论它的报告都必然命中。判据的 label 与它实际验的东西之间没有强制关系（apc/12 §0.13）。
+>
+> **诚实边界**：`requiredVerdicts` 把「答案」编进了判据 —— 它只对**这个** sample task 有意义（换一个待审 diff 就必须换 args，甚至该判 `covered`）。这是 design-review 用同一个 arg 时已登记的取舍，不是新问题。
+```
+（上面四行是**真引用**、可原样复核——照抄这个形状不会把如实的报告判红；换成你自己那轮的真行号即可。）
+四段中任意一段**只能**二选一：给可复核引用，或显式 `N/A —` + 真理由（`N/A` 后面空着/敷衍 <20 字符同样判红）。**不许**把段名写进散文当作"覆盖过了"。
+**引用写法三条（判据按这个复核，写错会把如实的报告判红）**：
+1. **必须 repo-root-relative**：写 `src/lib/orphan-vacuum.ts:131`，不要写简写 `lib/orphan-vacuum.ts:131`，也不要写绝对路径。
+2. **计数不是行号**：`rg -c` 输出的 `path:12` 是"12 个命中"。要引用计数就写成 `count=12`；若整行只贴 `rg -c` 的裸 `path:数字`，判据会认出它是计数并跳过，但**别把它混在句子里**，那样会被当行号复核。
+3. **散文里出现的 `path:line` 一样会被复核**——报告里任何一处 `path:line` 都是一次声明。拿不准就只写路径不写行号。
+## 产出（副作用 oracle，报告里必须给）
+1. **独立性证据**：`git log` 作者 ≠ 评审者。
+2. **四段 findings**：按严重度排序，每条 `{severity, segment, file:line, finding, failureScenario}`。
+3.（挂 task 时）**criterion 上报行** + review artifact 落 `im_assets`（可回读）。
+**两个承重 oracle（本 skill 唯一有意义的判据）**：
+- **正控**：diff 里**真存在**的缺陷，findings **必须点出它**（有 file:line + 失败场景）。抓不到 = 评审失效。
+- **负控**：**干净的 diff**（无真缺陷），**不得虚报 blocker/major**。把正常代码说成 bug = 评审同样失效（这类假阳会淹没真信号、教 owner 无视评审）。
+**不许**：报没有 file:line 的 finding；报说不清失败场景的"感觉不对"；纠 CI 会抓的 lint/类型/格式；自评自的 diff。
+## 诚实边界
+- **LLM 评审是非确定性的**：本 skill **不保证抓出所有缺陷**，也不保证零漏报。它保证的是"走完四段 + 每条 finding 可核验（file:line + 失败场景）+ 不自评"。深/隐蔽的缺陷（跨文件时序、需要真跑才暴露的）可能漏——这类要靠 test-runner 真跑 + 多轮评审兜，不靠单次 review 打包票。
+- 四段里"历史上下文"依赖 `git blame`/`git log` 可读；shallow clone（daemon `--depth 1`）下历史不全，该段要显式标注"历史深度受限"。
+- 本 skill 只产 findings，不改代码——修由实施 agent 按 findings 回改，再进下一轮评审。
+## PKF 直写（研发回环 · doc07 §B2 写入点①）
+**产出时机**：四段评审出 findings 后，把本轮评审结论**直写成一张 PKF 记忆页**（pageType=`decision`，ReviewCard 语义 apc/09 §1）——同一页既是回用户侧的富评审报告，也是可召回的记忆页。这与经验抽取（durable 教训走 memory skill 的 CONSTRUCT→PLACE→WRITE）并存，不互相取代（doc07 §B1）。这一步是上面 criterion 上报**之后**的投影，不改评审的任何一步。
+**语法照 `pkf-writing` skill**——本 skill 不再内嵌语法骨架（frontmatter / typed link / 数据块写法都在那边）。写入面**不新造**：code agent 走 `prismer memory write`（SS-14 §4.3 appendix；hermes 侧是 native `memory_write`）。
+**声明**（doc10 §2.5 格式，报告末尾一行）：
+```
+PKF: prismer://workspace/<ws>/memory/<path>
+```
+写入面不可达时如实声明 `PKF: none — 写入面不可达（<哪一条>）`，**绝不允许**为了满足规则而假装写了。
+**回读**：声明后必须回读该页（`pkf_read` / memory read），确认**真实存在、正文非空**且与结论一致（结论段的 `derived-from`/`contradicts` 指向必须可解析：无对应 SPEC 页就删 `derived-from` 行，无被推翻决策就删 `contradicts` 行）；typed link 的 `prismer://` 目标必须**真实存在**（validator 规则 2c/4 挡 `invalid-prismer-host`），无对应页就删该 link 行、宁缺勿造伪目标；写入自动挂 INDEX 反孤儿锚（SS-14 §4.2），优先 edit 既有页而非 dump 新叶（PLACE 治理照走）。
+<!-- APC-ACK:v1 -->
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+执行本 skill 的**第一步**，先落一条调用回执：
+```bash
+cloud skill ack code-review --task "$PRISMER_TASK_ID"
+```
+**按退出码分流**（这条命令的退出码是承重信息，禁止用 `||` 兜底、`; true`、
+`set +e` 或重定向把它抹掉）：
+| exit | 含义 | 你要做的 |
+| --- | --- | --- |
+| `0` | 回执已落库（`im_task_logs.action='skill_ack'`） | 继续执行本 skill |
+| `3` | **无 task 上下文**——本次运行没有 task，产不出回执 | 继续执行本 skill；但本次运行**没有回执**，任何报告里都不得声称已 ack |
+| `4` | 你不是该 task 的 assignee，服务端拒绝 | 停下并上报：回执只能由执行该 task 的 agent 产生 |
+| `1` | 其它失败（网络 / 服务端） | 重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」 |
+回执只证明本 skill **被调度**，不证明**执行正确**——效果证明由本 skill 自己的
+acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。
+<!-- /APC-ACK:v1 -->

package/apc/skills/code-review/skill.json ADDED Viewed

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "slug": "code-review",
+  "name": "Code Review",
+  "description": "Review a diff against its acceptance criteria in four segments (convention adherence, correctness/bug scan, historical-context regressions, test-coverage gaps), executed by a NON-implementing agent (reviewer != commit author). Produce findings sorted by severity, each with file:line and a concrete failure scenario. A planted defect must be surfaced; a clean diff must not be over-reported.",
+  "category": "review",
+  "version": "1.1.0",
+  "license": "MIT",
+  "compatibility": [
+    "claude-code"
+  ],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": [
+        "git",
+        "rg"
+      ],
+      "capabilities": [
+        "prismer.task.verify-criterion"
+      ]
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Four-segment review of a REAL repo diff whose reasoning hides a data-loss defect, by a non-implementer",
+      "prompt": "Run the code-review skill as a NON-implementing reviewer on the diff below. This is a REAL diff from this repository (commit `a31963a7`), and the code it touches is still on disk — so every `file:line` you report is re-read off disk and re-verified. First establish reviewer independence: you are NOT the author of this diff (state it explicitly; a real run proves it via `git log -1 --format='%an <%ae>' a31963a7`). Then run the FOUR review segments by name — [1] convention adherence, [2] bug scan / correctness, [3] historical context, [4] test coverage — and produce findings sorted by severity (blocker/major/minor), each with a real `file:line` and a failure scenario (how it actually breaks).\n\n--- DIFF UNDER REVIEW (new file `src/im/sql/528_task_log_nullable_taskid_for_ops_audit.sql`, plus the vacuum descriptor it reasons about):\n```\n+-- Migration 528: make im_task_logs.taskId NULLABLE so ops-accountability audit\n+-- rows are ALWAYS written, even for a task-less gated approval.\n+--\n+-- Orphan-vacuum safety: src/lib/orphan-vacuum.ts matches orphans with\n+--   `taskId NOT IN (SELECT id FROM im_tasks)`. In SQL `NULL NOT IN (...)`\n+--   evaluates to NULL (not TRUE), so null-taskId rows are NEVER flagged/vacuumed\n+--   regardless of the table's `fkNullable` descriptor — this change cannot cause\n+--   audit-row loss.\n+ALTER TABLE im_task_logs MODIFY COLUMN taskId VARCHAR(30) NULL;\n```\nand, unchanged by this diff, in `src/lib/orphan-vacuum.ts` the descriptor row for that same table read:\n```\n  { name: 'im_task_logs', parentTable: 'im_tasks', fkColumn: 'taskId', fkNullable: false },\n```\n\n--- THE LOAD-BEARING DEFECT you MUST surface (it is real, and the false reasoning is still verbatim on disk): the migration's `Orphan-vacuum safety` paragraph is WRONG. `NULL NOT IN (subquery)` is only NULL-safe while the subquery returns at least one row; `NULL NOT IN (empty set)` evaluates to TRUE. So whenever `im_tasks` is empty (a cleared / freshly-reset database, then an orphan-vacuum run), `whereOrphan()` matches the task-less audit rows and DELETEs exactly the accountability records this migration exists to preserve — silent data loss. The descriptor must carry `fkNullable: true` so `whereOrphan()` emits an explicit `AND taskId IS NOT NULL` guard instead of leaning on three-valued logic.\n\n--- YOUR REVIEW MUST: (a) state reviewer independence (not the author); (b) surface the empty-parent-set / `NULL NOT IN` vacuum data-loss defect as a blocker or major finding WITH its concrete failure scenario (im_tasks empty → NOT IN over an empty set is TRUE → DELETE of legitimate task-less audit rows); (c) cover all four segments by name (convention, bug/correctness, historical context, test coverage — e.g. note that no test asserts a task-less audit row survives a vacuum run); (d) NOT fabricate unrelated blocking findings and not nitpick lint/formatting CI would catch.\n\n--- YOUR REPORT MUST USE THIS MACHINE-CHECKED OUTPUT CONTRACT (it is re-verified against the filesystem, so an invented file:line is caught):\n\nLine 1 — the review target you anchored on, exactly this shape:\n`CHANGE-POINT: im_task_logs @ src/im/sql/528_task_log_nullable_taskid_for_ops_audit.sql`\n\nThen the findings table, sorted by severity, one row per finding, FIRST CELL the real `file:line` (copy the line number from your own `rg -n` output — the cited line is read off disk; a missing file, an out-of-range line, or a blank line FAILS the review):\n```\n| file:line | severity | segment | finding | failureScenario |\n| --- | --- | --- | --- | --- |\n| src/im/sql/528_task_log_nullable_taskid_for_ops_audit.sql:25 | blocker | bug | ... | ... |\n| src/lib/orphan-vacuum.ts:131 | blocker | bug | ... | ... |\n```\nYou need at least 3 finding rows carrying a verified `file:line`, and at least 2 of your citations must land on a line that LITERALLY CONTAINS `im_task_logs` — a real line that is not a real search hit is not evidence, so `rg -n im_task_logs` first and cite from that output.\n\nThen the FOUR review segments, EACH on its own line with its EXACT key. The checker looks for the KEYED LINE — the words `convention` / `bug` / `history` / `coverage` appearing anywhere else in your prose do NOT count as covering that segment. Answer each with a real `file:line` you actually looked at while running that segment (re-read off disk), or `N/A — <reason ≥20 chars>` when that segment genuinely had nothing to look at:\n```\n- SEGMENT-convention: <path:line>\n- SEGMENT-bug: <path:line>\n- SEGMENT-history: <path:line> | N/A — <why>\n- SEGMENT-coverage: <path:line> | N/A — <why>\n```\n\nThen `changeSummary`, `openQuestions[]` and `residualTestGaps[]` as prose.\n\nHARD RULE: do not guess line numbers. Every `file:line` anywhere in your report is re-read off disk. Citations MUST be repo-root-relative (`src/lib/orphan-vacuum.ts:131`, never an abbreviated `lib/orphan-vacuum.ts:131` and never an absolute path). A `rg -c` HIT COUNT is not a line number — write counts as `count=N`, never inline as `path:N`.",
+      "expectedArtifacts": [
+        "independence statement: reviewer identity != commit author of the reviewed diff",
+        "a `CHANGE-POINT: <symbol> @ <path>` declaration naming the review target actually audited",
+        "findings table sorted by severity, each row {file:line, severity, segment, finding, failureScenario}, every file:line resolving on disk and ≥2 landing on a line containing `im_task_logs`",
+        "the NULL-NOT-IN / empty-parent-set vacuum data-loss defect surfaced as blocker or major, with its failure scenario",
+        "changeSummary + openQuestions + residualTestGaps"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "every finding cites REAL evidence — each file:line re-read off disk (existence + line range + non-blank), ≥2 landing on a line that actually contains the reviewed symbol, ≥3 finding rows carrying a verified citation, anchored on this task's review target",
+          "type": "structured",
+          "checker": "cited-evidence",
+          "args": {
+            "minRows": 3,
+            "minAnchoredRows": 2,
+            "anchorMinLength": 4,
+            "expectedChangePoint": {
+              "symbol": "im_task_logs",
+              "path": "src/im/sql/528_task_log_nullable_taskid_for_ops_audit.sql"
+            }
+          },
+          "match": "<structured:cited-evidence>",
+          "required": true
+        },
+        {
+          "label": "reviewer independence stated (non-implementer / not the author)",
+          "match": "(independ\\w*|non-?implement\\w*|did\\s+not\\s+(write|author)|not\\s+the\\s+(author|implementer|committer)|reviewer\\s*(≠|!=|is\\s+not)|git\\s+log|独立|非实施|非.{0,2}实施|不是.{0,8}(作者|实施|提交)|并非.{0,8}作者)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "the real defect surfaced (NULL NOT IN over an empty parent set → audit-row deletion)",
+          "match": "(not\\s+in|三值|three[- ]?valued|empty\\s+(set|subquery|parent|table)|空(集|表|父)|fknullable|is\\s+not\\s+null|vacuum|删(除|掉)|delete\\w*|data\\s*loss|数据丢失|审计行)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "severity sorting vocabulary present",
+          "match": "(\\b(blocker|major|minor|critical|high|medium|low|severity)\\b|严重|阻断|致命|高危)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "all four review segments answered on their own keyed line — each carrying a citation verified on disk, or an explicit N/A with a real reason (a segment is NOT covered by its keyword appearing somewhere in the prose)；且 SEGMENT-bug 必须判 `gap`——这个 diff 确实藏着一条数据丢失缺陷，一份『无 blocker、建议合入』的评审必须判红",
+          "type": "structured",
+          "checker": "dimension-coverage",
+          "args": {
+            "dimensions": [
+              "SEGMENT-convention",
+              "SEGMENT-bug",
+              "SEGMENT-history",
+              "SEGMENT-coverage"
+            ],
+            "minReasonChars": 20,
+            "requiredVerdicts": {
+              "SEGMENT-bug": "gap"
+            }
+          },
+          "match": "<structured:dimension-coverage>",
+          "required": true
+        },
+        {
+          "label": "finding carries a concrete failure scenario (how it breaks)",
+          "match": "(failure\\s*scenario|how\\s+it\\s+(breaks|fails)|会(坏|崩|失败|抛|删)|when\\b[\\s\\S]{0,60}(empty|null)|场景|输入.{0,20}(空|null)|空.{0,20}(时|会))",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": [
+      "local-filesystem",
+      "workspace-tasks"
+    ],
+    "humanApprovalRequiredFor": []
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/apc/12-skill-acceptance-tasks.md",
+      "docs/apc/05-devchain-gaps-and-skills.md",
+      "docs/apc/07-ui-kit-index-and-pkf-loop.md",
+      "docs/apc/09-card-system-pkf.md",
+      "src/im/services/task-review-artifact.service.ts",
+      "sdk/cloud/src/commands/task.ts",
+      "sdk/prismer/src/bundle/structured-criteria.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-07-24T00:00:00Z"
+  }
+}

package/apc/skills/design-review/SKILL.md ADDED Viewed

@@ -0,0 +1,122 @@
+---
+name: design-review
+description: Five-dimension design audit (frontend UI/UX · server data-model & flow · endpoint spec · daemon-runtime/SDK & local-cache-first · built-in skill/agent-role), executed by a NON-implementing agent. Every dimension gets a verdict; N/A only with a stated reason. A dimension the design silently skipped must be surfaced as a gap; covered dimensions must not be over-reported.
+license: MIT
+scope: common
+compatibility:
+  - claude-code
+allowed-tools:
+  - Bash
+metadata:
+  category: review
+---
+# design-review
+对一个**改动方案 / diff**做 **CLAUDE.md 强制的五维变更审计**，产出每一维的判定（covered / gap / N-A-带理由），由**非实施 agent** 执行（`apc/05` §2 S6 · `apc/12` design-review 行；与 S5 code-review 同精神——实施者不自审自的设计）。
+**什么时候用**：一个 design doc / migration / ADD COLUMN / 新 endpoint / UI 重做进评审门时，需要独立核对它有没有把五维都想全。这是设计期的漏，比 phase 末期补漏便宜 10×（CLAUDE.md 五维审计）。
+## 评审独立性（第一铁律，P2-17）
+**评审由非实施 agent 执行**——设计者不自审自的方案，与 no-self-approval 同精神。若你就是这份设计的作者 → 停手，让另一个 agent 审。
+## 五维（缺一维 = 未闭合；N/A 也要显式写理由）
+照 CLAUDE.md「Five-Dimension Change Audit」逐维答。**任一维标"未考虑"/"待后续评估"不能进实施**；**N/A 也要显式写原因**。
+| # | 维度 | 必答问题（摘 CLAUDE.md） | 证据手段 |
+| --- | --- | --- | --- |
+| 1 | **前端 UI/UX 渲染交互** | 用户在哪儿感知？哪些组件/hook/路径改？破坏交互肌肉记忆吗？刷新/跨设备？错误态如何 surface？ | `rg` 组件/路由 |
+| 2 | **服务端 data-model & 数据流** | 哪些 Prisma model / SQL table 改？migration 编号？读/写/缓存路径？同事务保证？跨实例 fan-out？ | `rg` schema；`ls src/im/sql \| sort \| tail` 看下一个编号；**双 Prisma**（SQLite + MySQL）都改了吗 |
+| 3 | **Endpoint spec** | 新增/改/弃用哪些 HTTP/WS/SSE？req/resp schema？认证级别？错误码？兼容策略？SDK 类型同步？ | `rg` 路由/handler |
+| 4 | **Daemon runtime / SDK & local-cache-first** | daemon SDK 要适配吗？本地 SQLite/FS/asset-cache 变化？离线 fallback？daemon↔cloud 版本协商？多语言 SDK 同步？ | `rg` runtime/；想 local-first：**cloud-only 的东西 daemon 学得到吗** |
+| 5 | **Built-in skill / agent-role** | 影响 SKILL.md / AGENTS.md / SOUL.md / operatingPrinciples 吗？要新 built-in skill？role template backfill？agent 端 prompt 更新？ | `rg` built-in-skills/ · role template |
+## Procedure
+### 1. 独立性自证（若挂 task）— 你不是设计作者
+### 2. 逐维审，每维产一条判定
+对每一维给一行判定，形状：
+```
+{ dimension: 1..5,
+  verdict: covered | gap | n/a,
+  reason: "<covered: 方案怎么覆盖的 + 残留问题 / gap: 漏了什么、会怎么坏 / n/a: 为什么这维不适用>" }
+```
+- **`gap` 是承重判据**：方案**没提**的维度，标 `gap` 并说清"这个洞会怎么坏"（如：cloud-only 的 cap，daemon 本地 LLM 路径学不到 → 离线不 enforce）。**别因为方案没写就默默跳过当它 covered**——静默跳过正是五维审计要抓的头号反 pattern（单维过度聚焦）。
+- **`n/a` 必须带理由**：一维确实不适用（纯计费门不碰 agent 能力 → 第 5 维 N/A），显式写理由。**不许留空、不许"待评估"。**
+- **`covered` 不虚报**：方案**真覆盖**的维度，标 covered、只列真实残留问题（错误码待补、跨设备回显待确认）。**不要**把正常设计说成 blocker——假阳会淹没真信号（照 S5 code-review "干净 diff 不虚报"）。
+### 3. 汇总 + 点出被静默跳过的维度
+产出：
+- **五维判定表**（每维 covered/gap/n-a + reason）。
+- **承重发现**：被方案**静默跳过**的维度（那个 enforcement/兼容/数据主权的洞）。
+- **openQuestions[]**：拿不准的（不是 gap）。
+## 输出契约（机器判据按这个复验，别自由发挥格式）
+本 skill 的验收判据不是「报告里出现了 `daemon` / `prisma` 这些词」——旧判据就是六条这样的 `match`，**一句 `npm run prisma:generate` 就能让"数据模型维已答"变绿**。现在判据找的是**每一维自己那一行**，并把该行的引用**读回磁盘复核**（`structured-criteria.ts` 的 `dimension-coverage`）。
+**五维逐行作答**（每维**独占一行 + 固定 key**，行首先给 verdict，再给理由，最后给证据）：
+```
+- [1] frontend-uiux: covered — <覆盖点 + 残留问题> | <path:line>
+- [2] server-data-model: covered — <…> | <path:line>
+- [3] endpoint-spec: covered — <…> | <path:line>
+- [4] daemon-runtime-sdk: gap — <洞是什么、会怎么坏> | <daemon/runtime 侧真要改的 path:line>
+- [5] skill-agent-role: gap — <…> | <path:line>    或    N/A — <理由 ≥20 字符>
+```
+判据强制三条：
+1. 每维的行**必须以 verdict 开头**：`covered` / `gap` / `N/A`（中文 `已覆盖` / `缺口` / `不适用` 同义）。
+2. `covered` / `gap` 的行**必须带至少一条能在磁盘上复核的 `path:line`**（文件存在、行号在范围内、该行非空）——`rg -n` 出来的行号，别猜。这就是"对码"：说方案漏了 daemon 层，就得指出 daemon 层**真正**要改的那一行。
+3. `N/A` 的行**必须带理由**（去空白后 ≥20 字符）；只写 `N/A` 判红。
+引用写法：**必须 repo-root-relative**（`src/im/api/routes.ts:314`，不要简写成 `im/api/routes.ts:314`，也不要绝对路径）；`rg -c` 出的 `path:12` 是**命中计数不是行号**，要写就写 `count=12`。
+**承重维度的 verdict 是被钉死的**：sample task 里 `daemon-runtime-sdk` 必须是 `gap`。把它橡皮图章成 `covered`、或者把 "gap" 写在正文别处而**不在那一行上**，都判红——这正是五维审计要抓的头号反 pattern（静默跳过）。
+## 产出（副作用 oracle，报告里必须给）
+1. **五维全答**：五个维度逐一有判定，**无一维留空**（N/A 也带理由）。
+2. **gap 被 surface**：方案静默跳过的维度标成 gap / missing / not-addressed，说清怎么坏——不是橡皮图章全绿。
+3. **covered 不虚报**：真覆盖的维度不编造 blocker。
+**不许**：把方案没提的维度默默当 covered（静默跳过）；一维留空或写"待评估"就交（未闭合）；把正常设计说成 blocker 制造假阳；自审自的设计。
+## 诚实边界
+- **LLM 设计评审是非确定性的**：本 skill **不保证**抓出所有设计缺陷，也不保证零漏报/零虚报。它保证的是"五维逐维走一遍 + 每维判定可核验（covered/gap/n-a 带理由）+ gap 说清怎么坏 + 不自审"。深层的跨维耦合缺陷可能漏——靠多轮评审 + 真实施后 test-runner 兜，不靠单次审打包票。
+- 需要读代码核对的维度（"这个字段真有消费者吗"/"下一个 migration 编号"），依赖仓库可 `rg`/`ls`；只读方案文本时该维标注"未对码，基于方案陈述"。
+- 本 skill 只产判定，不改设计——修由设计者按判定回改，再进下一轮审。
+<!-- APC-ACK:v1 -->
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+执行本 skill 的**第一步**，先落一条调用回执：
+```bash
+cloud skill ack design-review --task "$PRISMER_TASK_ID"
+```
+**按退出码分流**（这条命令的退出码是承重信息，禁止用 `||` 兜底、`; true`、
+`set +e` 或重定向把它抹掉）：
+| exit | 含义 | 你要做的 |
+| --- | --- | --- |
+| `0` | 回执已落库（`im_task_logs.action='skill_ack'`） | 继续执行本 skill |
+| `3` | **无 task 上下文**——本次运行没有 task，产不出回执 | 继续执行本 skill；但本次运行**没有回执**，任何报告里都不得声称已 ack |
+| `4` | 你不是该 task 的 assignee，服务端拒绝 | 停下并上报：回执只能由执行该 task 的 agent 产生 |
+| `1` | 其它失败（网络 / 服务端） | 重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」 |
+回执只证明本 skill **被调度**，不证明**执行正确**——效果证明由本 skill 自己的
+acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。
+<!-- /APC-ACK:v1 -->

package/apc/skills/design-review/skill.json ADDED Viewed

@@ -0,0 +1,88 @@
+{
+  "schemaVersion": 1,
+  "slug": "design-review",
+  "name": "Design Review",
+  "description": "Five-dimension design audit (frontend UI/UX · server data-model & flow · endpoint spec · daemon-runtime/SDK & local-cache-first · built-in skill/agent-role) executed by a NON-implementing agent. Every dimension must be answered; N/A is allowed only with a stated reason. A dimension the proposal silently skipped must be surfaced as a gap; a proposal that legitimately covers a dimension must not be over-reported.",
+  "category": "review",
+  "version": "1.1.0",
+  "license": "MIT",
+  "compatibility": [
+    "claude-code"
+  ],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": [
+        "git",
+        "rg"
+      ],
+      "capabilities": []
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Five-dimension audit of a proposal that silently skips the daemon/SDK dimension",
+      "prompt": "Run the design-review skill (five-dimension audit) as a NON-implementing reviewer on the PROPOSAL below. Audit it across ALL FIVE dimensions and, for each, give a one-line verdict (covered / gap / N/A-with-reason) BACKED BY THE REAL REPO: `rg` for the actual file this dimension would touch and cite it as `path:line`. --- PROPOSAL: 'Add a per-user daily LLM spend cap. (1) DB: ADD COLUMN `daily_cap_credits` to `im_users` via a new migration; write path updates it in the settings save handler. (2) Endpoint: new `PATCH /api/im/me/spend-cap` (JWT auth) sets the cap; `GET /api/im/me/spend-cap` reads it. (3) Frontend: a new number field in the Settings > Billing page, with an inline error toast when the value is negative.' --- Note what this proposal does NOT address: the daemon/SDK layer runs LLM calls locally and caches spend locally (local-cache-first), so a cloud-only cap that the daemon never learns about will not be enforced on the daemon's LLM path — yet the proposal says nothing about daemon↔cloud sync, offline fallback, or the local spend cache. It also says nothing about the built-in-skill / agent-role dimension. Your audit MUST: (a) walk all five dimensions by name; (b) mark the daemon-runtime/SDK dimension as a GAP (the enforcement hole) rather than silently passing it; (c) either flag the built-in-skill/agent-role dimension as a gap or mark it N/A WITH a stated reason (do not leave it unanswered); (d) not fabricate blocking problems in the three dimensions the proposal legitimately covers (frontend, data-model, endpoint) — note them as covered, listing only genuine residual questions.\n\n--- YOUR REPORT MUST USE THIS MACHINE-CHECKED OUTPUT CONTRACT. The checker looks for each dimension's OWN KEYED LINE and re-reads every citation off disk, so the word appearing elsewhere in your prose does not count as answering that dimension, and an invented path:line is caught.\n\nFive lines, each with its exact key, opening with the verdict, then the reason, then the evidence:\n```\n- [1] frontend-uiux: covered — <what the proposal covers + residual question> | <path:line>\n- [2] server-data-model: covered — <...> | <path:line>\n- [3] endpoint-spec: covered — <...> | <path:line>\n- [4] daemon-runtime-sdk: gap — <what the hole is and how it actually breaks> | <path:line in the daemon/runtime source that would have to change>\n- [5] skill-agent-role: gap — <...> | <path:line>    (or)    N/A — <reason ≥20 chars>\n```\nRules the checker enforces: a dimension line must OPEN with `covered`, `gap` or `N/A`; a `covered` or `gap` line must carry at least one `path:line` that resolves on disk (real file, line in range, non-blank) — `rg -n` it, do not guess line numbers; an `N/A` line must carry a reason of at least 20 non-space characters. Dimension [4] must carry the verdict `gap` — rubber-stamping it `covered`, or leaving it off its keyed line while saying 'gap' somewhere else in the prose, FAILS. Citations MUST be repo-root-relative (`src/im/api/routes.ts:314`, never an abbreviated `im/api/routes.ts:314` and never an absolute path); a `rg -c` HIT COUNT is not a line number, write counts as `count=N`.\n\nThen your prose summary: the per-dimension verdict table, the load-bearing finding (the silently-skipped daemon/SDK dimension), and `openQuestions[]`.",
+      "expectedArtifacts": [
+        "five keyed dimension lines (frontend-uiux / server-data-model / endpoint-spec / daemon-runtime-sdk / skill-agent-role), each opening with a verdict and backed by a path:line that resolves on disk or an explicit N/A + reason",
+        "the daemon-runtime/SDK dimension carrying the `gap` verdict on its own keyed line (local-cache-first enforcement hole), not silently passed",
+        "the built-in-skill/agent-role dimension answered (gap or N/A-with-reason), not left blank",
+        "prose summary: verdict table, load-bearing finding, openQuestions — the three covered dimensions not over-reported as fabricated blockers"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "all five dimensions answered on their own keyed line — each backed by a citation re-verified on disk, or an explicit N/A with a real reason (no dimension may be silently dropped)",
+          "type": "structured",
+          "checker": "dimension-coverage",
+          "args": {
+            "dimensions": [
+              "frontend-uiux",
+              "server-data-model",
+              "endpoint-spec",
+              "daemon-runtime-sdk",
+              "skill-agent-role"
+            ],
+            "minReasonChars": 20
+          },
+          "match": "<structured:dimension-coverage>",
+          "required": true
+        },
+        {
+          "label": "the silently-skipped daemon-runtime/SDK dimension carries the `gap` verdict ON ITS OWN keyed line with on-disk evidence — a `covered` rubber stamp, or the word 'gap' floating elsewhere in the prose, fails",
+          "type": "structured",
+          "checker": "dimension-coverage",
+          "args": {
+            "dimensions": [
+              "daemon-runtime-sdk"
+            ],
+            "requiredVerdicts": {
+              "daemon-runtime-sdk": "gap"
+            },
+            "minReasonChars": 20
+          },
+          "match": "<structured:dimension-coverage:verdict>",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": [
+      "local-filesystem"
+    ],
+    "humanApprovalRequiredFor": []
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/apc/12-skill-acceptance-tasks.md",
+      "docs/apc/05-devchain-gaps-and-skills.md",
+      "CLAUDE.md#Five-Dimension-Change-Audit",
+      "sdk/apc/skills/code-review/SKILL.md",
+      "sdk/prismer/src/bundle/structured-criteria.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-07-24T00:00:00Z"
+  }
+}