@prismer/runtime 2.0.7 → 2.2.55

package/apc/skills/impact-trace/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: impact-trace
+description: For a change point (function / type / endpoint / SQL column), enumerate its real blast radius across six dimensions with a grep citation per row, then derive the regression test scope. Every impact-table row must trace to a real search hit — never a self-asserted claim.
+license: MIT
+scope: common
+compatibility:
+  - claude-code
+  - prismer-sdk
+allowed-tools:
+  - Bash
+metadata:
+  category: analysis
+---
+
+# impact-trace
+
+给定一个**改动点**（函数 / 类型 / endpoint / SQL 列），产出它的**真实影响面**（受影响的调用方 / 契约消费者 / 持久化写入 / 双 Prisma schema / daemon-SDK 镜像 / skill-role 引用）+ 由此推导的**回归测试范围**（`apc/05` §2 S2 · `apc/12` impact-trace 行）。
+
+**什么时候用**：一个 bugfix / feature 改完，进 review 前需要知道"改这一处会波及哪些地方、要回归哪些层"；或评审要判断改动的 blast radius。
+
+铁律：**影响表的每一行都必须有 grep/search 证据（path+line）**。凭记忆或推理写"这里应该会用到"是开卷考试——本 skill 的产出只认真实搜索命中。你自己不是 ground truth，`rg` 的命中集才是。
+
+## 工具契约（签名以此为准，先核后用）
+
+| 命令 | 作用 | 备注 |
+| --- | --- | --- |
+| `rg <pattern> [path] -n` | 主力搜索：直接调用方 / 契约消费者 / 引用点 | `-n` 出行号（证据必须带行号）；`-l` 只列文件；`-t ts` 限类型 |
+| `rg -c <pattern>` | 命中计数（核对"没漏"用） | 计数对不上就是漏搜 |
+| `cloud code grep <pattern> --repo <abs> [--glob '*.ts']` | 白名单 repo 内搜索，输出 JSON `[{path,line,snippet,sha256}]` | 仅 `PRISMER_WORKSPACE_ROOT` 或 `~/.prismer/agents/<id>/scratch` 内；出带 sha 的可引用片段。`--glob` 只支持 `*.ext` 形态 |
+
+- `rg` 是本机主力；`cloud code grep` 用于要产出**可引用证据片段**（带 sha256）时。两者的命中集应当一致——不一致就查是不是路径白名单/glob 把一部分挡在外面了。
+- **不要**用单文件 grep 命中当全貌（memory `feedback_grep_full_range_for_seq_audit`）。搜完要核计数：`rg -c` 的总数 == 影响表行数（去掉 N/A 维度），对不上就是漏了。
+
+## 六维影响面（逐维搜，缺一维要么有证据要么写 N/A 理由）
+
+改动点波及面按六维穷举。**任一维标 N/A 必须写理由**；**双 Prisma 维度永远不许静默省略**（`apc/12` 负控：缺双 Prisma 维且无 N/A 理由 → 校验拒绝）。
+
+| # | 维度 | 怎么搜（示例） | 找什么 |
+| --- | --- | --- | --- |
+| 1 | **直接调用方** | `rg '\b<name>\b' -n -t ts` | 谁 import / 调用了这个符号 |
+| 2 | **契约消费者**（API/wire） | `rg '<endpoint-path>\|<event-code>\|<rpc-name>' -n` | HTTP 路由消费者、SDK 类型、wire 帧的两端 |
+| 3 | **持久化写入** | `rg '<column>\|<model>\.(create\|update\|upsert)' -n` | 谁写这张表/这个字段 |
+| 4 | **双 Prisma schema** | `rg '<field>' prisma/schema.prisma prisma/schema.mysql.prisma -n` | SQLite + MySQL 两份 schema 是否都要改（**不许省**） |
+| 5 | **daemon-SDK 镜像** | `rg '<name>' sdk/prismer-cloud/runtime/src -n` | cloud 侧改了，daemon/SDK 侧有没有对称的一份要跟着改 |
+| 6 | **skill / role 引用** | `rg '<name>' sdk/prismer-cloud/built-in-skills sdk/apc/skills -n` | SKILL.md / role template / prompt 里有没有引用它 |
+
+## Procedure
+
+### 1. 锚定改动点
+
+明确改动点的**精确标识**（符号名 / endpoint 路径 / 列名）。一个改动可能有多个改动点——逐个搜，别只搜一个。
+
+### 2. 逐维搜索，收集带行号的命中
+
+```bash
+# 维度 1：直接调用方（示例，把 <name> 换成真符号）
+rg '\b<name>\b' -n -t ts > /tmp/impact-callers.txt
+rg -c '\b<name>\b' -t ts    # 核对命中计数
+
+# 维度 4：双 Prisma（两份 schema 都要看）
+rg '<field>' prisma/schema.prisma prisma/schema.mysql.prisma -n
+```
+
+对每一维，把命中记成影响表的一行：`{ path, line, dimension, contract, risk }`。**没有命中的维度**：确认真的没有（不是搜错 pattern），然后写 `N/A + 理由`。
+
+### 3. 组装影响表（副作用产出 1）
+
+| path:line | 维度 | 契约 | 风险 | 回归 |
+| --- | --- | --- | --- | --- |
+| `src/foo.ts:42` | 直接调用方 | 传参 shape | 改签名会破 | T0 |
+
+**每行必须能回指一条 `rg`/`cloud code grep` 命中**。行数（不含 N/A 维）应等于去重后的真实命中数——自查：`影响表行数 == Σ rg -c`。
+
+### 4. 推导回归测试范围（副作用产出 2）
+
+按影响表命中的**文件所在层**映射到 tier（对齐 test-runner 选层规则）：
+
+| 命中落在 | 回归 tier |
+| --- | --- |
+| `src/lib/**` | T0 |
+| `src/im/**` / endpoint | T1 |
+| `src/app/**` | T2 |
+| e2e / 跨端 | T3 |
+| daemon `runtime/src/**` | daemon 测试（runtime vitest） |
+
+产出："本改动需回归 {tiers}，因为影响面落在 {层}"。
+
+### 5.（可选）上报 criterion
+
+若本 impact-trace 挂在一个 task 的 acceptance criterion 上，把结论上报：
+
+```bash
+cloud task verify-criterion "$PRISMER_TASK_ID" "<criterion-id>" --outcome passed \
+  --note "impact table: N rows, all grep-cited; regression scope: T0,T1"
+```
+
+`--outcome` 合法值恰好四个：`passed | failed | n/a | waived`。
+
+## 输出契约（机器判据按这个复验，别自由发挥格式）
+
+本 skill 的验收判据不是「报告里出现了某些词」，而是**把报告里的声明拿回文件系统复核**（`structured-criteria.ts` 的 `cited-evidence` / `dimension-coverage`）。所以报告必须带下面三样**可机器解析**的东西——形状对但内容假的报告会被当场判红。
+
+**① 改动点声明**（一行，锚点必须是本次真实改动点，且会被复核确实存在于该文件）：
+
+```
+CHANGE-POINT: <symbol> @ <path>
+```
+
+**② 影响表**（markdown 表，首列是 `path:line`）：判据会**逐行把 `path:line` 读回磁盘**——文件不存在 / 行号越界 / 该行是空行，任意一条就判红；并且至少 3 条引用所在的**那一行必须真的含改动点符号**（"真实存在的行" ≠ "真实的搜索命中"），**且这些命中要落在 ≥3 个不同文件里**——把一条真命中抄满整张表是"单命中报告"，不是影响面（实证：一条真 `path:line` 复制 12 遍，加固前 5/5 全绿）。
+
+```
+| path:line | 维度 | 契约 | 风险 | 回归 |
+| --- | --- | --- | --- | --- |
+| src/foo.ts:42 | direct-callers | 传参 shape | 改签名会破 | T0 |
+```
+
+**③ 六维逐行作答**（每维**独占一行 + 固定 key**）。判据找的是**这一行**，报告别处出现同一个词（比如正文里出现 `npm run prisma:generate`）**不算答过**——这正是旧判据 `match:"prisma"` 被证伪的地方：
+
+```
+- [1] direct-callers: <path:line>
+- [2] contract-consumers: <path:line>
+- [3] persistence-writers: <path:line> | N/A — <理由 ≥20 字符>
+- [4] dual-prisma: <path:line> | N/A — <理由 ≥20 字符>
+- [5] daemon-sdk-mirror: <path:line>
+- [6] skill-role-references: <path:line> | N/A — <理由 ≥20 字符>
+```
+
+**N/A 必须带理由**（去空白后 ≥20 字符）；只写 `N/A` 判红。**行号照抄 `rg -n` 的真实输出，不许凭印象写。**
+**每一维要有自己的证据**：同一条 `path:line` 最多给 2 个维度当证据，第 3 个维度再引它就判红（N/A 维不受影响，它本来就没有引用）。
+
+## 产出（副作用 oracle，报告里必须给）
+
+1. **影响表**：每行 `{path:line, 维度, 契约, 风险}` + 找到它的那条搜索。**行的真实性 = grep 命中**，不是叙述。
+2. **六维覆盖**：六维全答；N/A 维带理由（双 Prisma 维不许静默省）。
+3. **回归范围**：由影响表的层映射推出的 tier 集。
+4.（若有 task）**criterion 上报行**：`cloud task verify-criterion` 落库 outcome，可回读 acceptance view 确认。
+
+**不许**：把没有搜索命中的行写进影响表；漏搜一个真实调用方（`rg -c` 计数不核）；把双 Prisma 维度静默省掉；断言聊天文本而非 path:line 证据。
+
+## 诚实边界
+
+- `rg` 命中集是"文本匹配"的 ground truth，不是"语义调用图"——动态派发 / 字符串拼出来的引用 / 反射，文本搜不到。影响表覆盖的是**可被文本搜索命中的**引用面；无法静态搜到的动态引用要显式标注为已知盲区，不得声称"影响面已穷举"。
+- 回归范围是"应当回归哪些层"的推导，**不代替真跑**——真跑归 test-runner skill。
+
+<!-- APC-ACK:v1 -->
+
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+
+执行本 skill 的**第一步**，先落一条调用回执：
+
+```bash
+cloud skill ack impact-trace --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/impact-trace/skill.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 1,
+  "slug": "impact-trace",
+  "name": "Impact Trace",
+  "description": "Given a change point (function/type/endpoint/schema), enumerate its real blast radius — direct callers, contract consumers, persistence writers, dual Prisma schemas, daemon-SDK mirrors, skill/role references — with a grep-cited evidence row per line, and derive the regression test scope. Every impact-table row must trace to a real search hit, never a self-asserted claim.",
+  "category": "analysis",
+  "version": "1.1.0",
+  "license": "MIT",
+  "compatibility": ["claude-code", "prismer-sdk"],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": ["rg"],
+      "capabilities": []
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Trace the real blast radius of matchAcceptanceCriteria and derive the regression scope",
+      "prompt": "Run the impact-trace skill on this REAL change point in the current repo. CHANGE POINT: the exported function `matchAcceptanceCriteria` (defined in `sdk/prismer/src/bundle/index.ts`). Imagine its signature is about to change. Produce its real blast radius — every impact-table row MUST trace to a real search hit (path:line), never a self-asserted claim. Run these steps from the repo root and report what you actually observed: (1) `rg -n matchAcceptanceCriteria --glob '*.ts'` — this is your evidence set; every impact-table row must cite one of these path:line hits. (2) `rg -c matchAcceptanceCriteria --glob '*.ts'` — reconcile the hit count against your table (no missed real caller, no fabricated one). CAREFUL: `rg -c` prints `path:COUNT`, which is NOT a `path:line` citation. Report those counts as `count=N` (e.g. `src/foo.ts count=12`) or paste the raw `rg -c` output with each entry alone on its own line — never inline a bare `path:<count>` inside a sentence or a table cell, because every `path:<number>` you write in a claim position is re-read off disk as a LINE NUMBER. (3) Walk ALL SIX dimensions by name and answer each. (4) Derive the regression test scope from the layers your hits fall in.\n\n--- YOUR REPORT MUST USE THIS MACHINE-CHECKED OUTPUT CONTRACT (it is re-verified against the filesystem, so an invented path:line is caught):\n\nLine 1 — the change point you traced, exactly this shape:\n`CHANGE-POINT: matchAcceptanceCriteria @ sdk/prismer/src/bundle/index.ts`\n\nThen the impact table — a markdown table, one row per REAL rg hit, the first cell being the `path:line` of that hit (the LINE NUMBER MUST BE THE REAL ONE from your rg output; the cited line is read off disk and must actually contain the symbol):\n```\n| path:line | dimension | contract | risk | regression |\n| --- | --- | --- | --- | --- |\n| sdk/prismer/src/bundle/index.ts:451 | direct-callers | ... | ... | daemon vitest |\n```\n\nThen the six dimensions, EACH on its own line with its exact key. Answer with a real `path:line` citation, or `N/A — <reason ≥20 chars>` when the dimension genuinely does not apply (a dimension may NEVER be silently dropped — the checker looks for the KEYED LINE, so the word appearing elsewhere in your report does not count):\n```\n- [1] direct-callers: <path:line>\n- [2] contract-consumers: <path:line>\n- [3] persistence-writers: <path:line> | N/A — <why>\n- [4] dual-prisma: <path:line> | N/A — <why>\n- [5] daemon-sdk-mirror: <path:line>\n- [6] skill-role-references: <path:line> | N/A — <why>\n```\n\nThen the derived regression scope (which tiers / which files must re-run, and why — from the layers your verified hits fall in).\n\nHARD RULE: every `path:line` anywhere in your report is re-read off disk. A path that does not exist, a line number past end-of-file, or a blank line makes the report FAIL. Do not guess line numbers — copy them from your real rg output.\n\nHARD RULE (BREADTH): the hits you cite must come from at least 3 DIFFERENT files, and no single `path:line` may be the evidence for more than 2 of the six dimensions. Walk the whole rg output — repeating one real hit under every row and every dimension is a one-hit report, not a blast radius, and it FAILS. Citations MUST be repo-root-relative (`sdk/prismer/src/bundle/index.ts:451`, never an abbreviated `runtime/src/bundle/index.ts:451` and never an absolute path).",
+      "expectedArtifacts": [
+        "a `CHANGE-POINT: <symbol> @ <path>` declaration naming the change point actually traced",
+        "impact table: one row per affected site with {path:line, dimension, contract, risk, regression}, each path:line a real rg hit that resolves on disk to a line containing the symbol",
+        "the six keyed dimension lines, each answered with a verifiable citation or an explicit `N/A — reason` (dual-prisma never silently dropped; daemon-sdk-mirror surfaced)",
+        "derived regression test scope (which tiers / which files)"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "impact rows cite REAL grep evidence — every path:line re-verified on disk, ≥3 landing on a line that actually contains the traced symbol, spread over ≥3 distinct files, anchored on this task's change point",
+          "type": "structured",
+          "checker": "cited-evidence",
+          "args": {
+            "minRows": 3,
+            "minAnchoredRows": 3,
+            "minDistinctAnchorFiles": 3,
+            "anchorMinLength": 4,
+            "expectedChangePoint": {
+              "symbol": "matchAcceptanceCriteria",
+              "path": "sdk/prismer/src/bundle/index.ts"
+            }
+          },
+          "match": "<structured:cited-evidence>",
+          "required": true
+        },
+        {
+          "label": "all six dimensions answered on their own keyed line — citation verified on disk and not shared by more than 2 dimensions, or explicit N/A with a real reason (dual-prisma can never be silently dropped)",
+          "type": "structured",
+          "checker": "dimension-coverage",
+          "args": {
+            "dimensions": [
+              "direct-callers",
+              "contract-consumers",
+              "persistence-writers",
+              "dual-prisma",
+              "daemon-sdk-mirror",
+              "skill-role-references"
+            ],
+            "minReasonChars": 20,
+            "distinctCitations": { "maxDimensionsPerCitation": 2 }
+          },
+          "match": "<structured:dimension-coverage>",
+          "required": true
+        },
+        {
+          "label": "enumerates callers / blast radius (real caller set, not a vague summary)",
+          "match": "(\\b(caller|call[- ]?site|blast[- ]?radius|impact|affected|import)\\b|调用方|调用点|消费者|影响面|影响)",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "daemon-SDK mirror dimension surfaced",
+          "match": "\\b(daemon|runtime|sdk|mirror|镜像)\\b",
+          "type": "regex",
+          "flags": "is",
+          "required": true
+        },
+        {
+          "label": "derived regression test scope from affected surfaces",
+          "match": "(regression|回归测试|回归|tier|层级|T[0-4]\\b|test\\s*scope|测试范围|测试层|测试类型|vitest|test\\s*file|\\.test\\.|重跑|重新(运行|跑)|which\\s+(test|tier))",
+          "type": "regex",
+          "flags": "is",
+          "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",
+      "sdk/cloud/src/commands/code-grep.ts",
+      "sdk/prismer/src/bundle/structured-criteria.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-07-24T00:00:00Z"
+  }
+}

package/apc/skills/observability/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: observability
+description: Periodic health sweep of the running system via the debug pipeline (cloud logs / k8s / daemon / DB slices). On a real anomaly, open a bug task (--kind work_item) carrying the evidence refs so it re-enters the bugfix loop. A healthy sweep opens NO task — never fabricate a bug.
+license: MIT
+scope: common
+compatibility:
+  - claude-code
+  - prismer-sdk
+allowed-tools:
+  - Bash
+metadata:
+  category: observability
+---
+
+# observability
+
+用 **debug pipeline** 巡检运行中的系统（cloud log / k8s / daemon / DB 切片），**异常时开一个 bug task** 把证据带回 bugfix 循环（`apc/05` S10 · 生命周期矩阵**行 11 监控→回流**）。**触发器 = product205 定时任务后端**（已建，缺前端）挂周期巡检——本 skill 是那次巡检真正干的活，不悬空。
+
+**承重纪律**：
+- **healthy 扫描不开 task。** 没有异常就报"绿"并停手——**绝不**为了"有产出"造一个假 bug。一个无论系统健不健康都会建 task 的巡检 = 噪声制造机。
+- **异常 → bug task 必须带证据 ref。** bug task 的 description 要挂可追溯锚（pod / workspace / task id + debug 切片摘要，或把 bundle 产物 `cloud asset upload` 后引 `asset:<id>`）。空口"系统好像有问题"不是 bug task。
+- **oracle 是真 task 行，不是聊天叙述。** "我建了 bug task" 不算数——`cloud task create` 返回的真 id + 回读的 task 行才算。
+
+**什么时候用**：周期巡检（定时任务触发）或收到"系统是不是出问题了"时——先用 debug pipeline 取副作用切片核实，再决定是否回流。
+
+## 工具契约（签名以此为准，先核后用）
+
+| 命令 | 作用 | 输出/退出码 |
+| --- | --- | --- |
+| `npx tsx scripts/debug/admin-observability.ts capabilities [--env=local\|test\|prod]` | canonical Admin v1 discovery；读取 principal、capabilities、schema version 与 opaque contract digest | `0` 成功；不兼容/无权限非零 |
+| `npx tsx scripts/debug/admin-observability.ts logs --target-kind=service --target-id=prismer-cloud --purpose=<reason> [--since=15m] [--cursor=<opaque>] [--completeness=require-complete\|allow-partial]` | canonical `POST /api/admin/v1/logs:query` 只读快照；命令内部必须先 discovery；cursor 只能原样回传 | 默认 `require-complete`；置信边界完整 `0`，不满足 `3`，请求/合同错误 `1`，用法错误 `2` |
+| `cloud admin log-targets --kind <service\|sandbox\|daemon> --purpose <reason> [--workspace-id <id>] [--cursor <opaque>]` | daemon-held credential 下发现 DB-resolved logical targets；不接受 namespace/selector | `0` 完整成功；partial projection `2`；请求失败 `1` |
+| `cloud admin logs --target-kind <kind> --target-id <id> --purpose <reason> [--attach-to-task [taskId]]` | credentialless loopback 查询 service/sandbox/daemon；可经既有 daemon task-attach 把 JSON 证据绑定到 task | `0` 完整成功；partial `2`；失败 `1`；attach 要求 daemon dispatch + `PRISMER_ARTIFACTS_DIR` |
+| `npx tsx scripts/debug/inventory.ts [--env=local\|test\|prod] [--json]` | 全局索引：running pods / recent workspaces / recent tasks / **recent errors** | 人读 5 段 或 `--json` |
+| `npx tsx scripts/debug/bundle.ts <workspace\|task\|pod> <id> [--sections=db,system,k8s,daemon] [--stdout] [--since=ISO]` | 复合切片（DB+system-log+k8s+daemon） | 默认写 `./debug-bundle-*.json`，`--stdout` 打屏 |
+| `npx tsx scripts/debug/snapshot.ts <workspace\|task\|conversation\|container> <id> [--json\|--brief]` | DB 切片（task 终态行/runs/logs/approvals/assets） | 默认 compact，`--json` raw |
+| `npx tsx scripts/debug/logs.ts [--contains=text] [--since=ISO\|10m\|1h] [--level=...] [--json]` | cloud 进程 pino ring buffer | 每行一条 或 `--json` |
+| `cloud task create --title <t> --description <d> --kind work_item [--priority high] [--json]` | **开 bug task**（`--kind work_item` 是 board 投影） | 打印 `ID: <taskId>`（`--json` 出整行） |
+| `cloud task list [--json]` | 回读 task 行确认落库 | 0 成功 |
+
+- `--kind` 合法值**恰好两个**：`work_item`（默认，bug/工作项）/ `goal`。bug 巡检一律 `work_item`。
+- **鉴权**：debug pipeline 走 admin RBAC（`--env=local` dev 短路免鉴权；`--env=test|prod` 需 `PRISMER_API_KEY_TEST`/`PRISMER_API_KEY`）。coding agent 的 workdir env **不注入高危凭据**——test/prod 巡检由平台方持凭发起，不在 agent 的 bash 里裸读（`apc/05` §3 凭据可见性边界）。
+- **凭据边界**：canonical 命令没有 `--api-key` 参数，也不把 credential 写入 stdout、stderr 或产物；禁止 `env`、`printenv`、shell tracing（`set -x`）和把 Authorization header 拼进命令行。平台执行器在模型不可见边界注入 credential。
+- **合同边界**：只调用 `/api/admin/v1/capabilities` 与 `/api/admin/v1/logs:query`，不猜 403、不回退 legacy route、不猜 digest 算法。若平台固定了本次发布 digest，可由执行器注入 `PRISMER_ADMIN_CONTRACT_DIGEST` 做 exact match。
+
+## Workflow
+
+### 1. 先落调用回执（见文末 ACK 块），再做 canonical discovery + Cloud 日志快照
+
+APC 自动巡检默认要求完整结果。先调用 capabilities，再由同一命令进程完成 logs query：
+
+```bash
+mkdir -p .e2e-tmp/apc/observability
+npx tsx scripts/debug/admin-observability.ts capabilities \
+  > .e2e-tmp/apc/observability/admin-capabilities.json
+npx tsx scripts/debug/admin-observability.ts logs \
+  --target-kind=service --target-id=prismer-cloud --since=15m \
+  --purpose="periodic APC observability sweep" \
+  --completeness=require-complete \
+  > .e2e-tmp/apc/observability/admin-service-logs.json
+admin_logs_exit=$?
+```
+
+`admin_logs_exit=3` 表示所需置信边界不完整，**不得宣布 healthy**；读取 JSON 中的
+`requestId`、`sources[]`、`partial`、`attemptedSourceTiers`、`availableSourceTiers`、
+`confidenceBoundary.productionRetainedRequirement`、`contractDigest`、`evidenceHash` 后报告受限结论。
+`attemptedSourceTiers` 只说明服务端尝试过某 tier；只有 `availableSourceTiers` 才代表可用证据，
+retained source 为 `unavailable` 或 `error` 时严禁把它写成 retained evidence。
+只有 human 明确做探索性查询时才可传 `allow-partial`，且逐 source outcome 仍必须保留。`1/2` 是请求或
+用法失败，同样不能当作“没有 error”。canonical 输出可作为 task-bound evidence，但先确认其中不含凭据；
+不要长期保存为 loose file。
+
+生产环境的 `require-complete` 还有强 gate：必须同时看到
+`availableSourceTiers` 包含 `retained`、
+`confidenceBoundary.productionRetainedRequirement.satisfied=true`、稳定 ordering/continuity、
+完整 coverage、`truncated=false`、`mayDuplicate=false`。任一不满足均按退出码 `3` 处理。
+分页时只可把响应 `nextCursor` 原样作为下一次 `--cursor=<opaque>`；不得解析、修改或自行生成 cursor。
+SLS 当前只提供 offset continuation，服务端会明确标记 `continuity=best-effort`、`mayDuplicate=true` 和
+`partial=true`；即使 provider query 返回 Complete 也不得升级成完整证据。Sandbox/Daemon 查询前先用
+`cloud admin log-targets` 发现 logical id，禁止把 Pod、namespace 或 label selector 当 target id 猜测。
+
+### 2. 拉全局索引，覆盖其余信号面
+
+```bash
+mkdir -p .e2e-tmp/apc/observability
+npx tsx scripts/debug/inventory.ts | tee .e2e-tmp/apc/observability/inventory.md; echo "inventory exit=$?"
+npx tsx scripts/debug/inventory.ts --json > .e2e-tmp/apc/observability/inventory.json    # 机器形（可选）
+```
+
+**产物落 repo-relative 的 `.e2e-tmp/apc/observability/`（已在 `.gitignore`），不要落 `/tmp`**——判据要**读回**你引用的那一行，`/tmp` 从仓库根不可解析、跑完即毁的证据等于没有证据（同 test204「证据销毁反 pattern」）。**报告前不许删**这批产物。
+
+读 5 段：`pods`（有没有 pending/crash）· `workspaces` · `recent tasks`（有没有卡在 pending/running 超时）· **`recent errors`**（`error`/`warn` 级别）。**先索引再下钻**——不要一上来 `logs.ts --since=30m | grep`（那是 v0 习惯）。
+
+### 3. 锁定可疑目标 → 下钻取副作用切片
+
+对索引里冒出的可疑目标（报错的 pod / 卡死的 task / 异常 workspace）一次拿全套：
+
+```bash
+# 已知某 task/workspace/pod 可疑 → 复合切片
+npx tsx scripts/debug/bundle.ts task <taskId> --sections=db,system,k8s,daemon --stdout > .e2e-tmp/apc/observability/bundle.json
+# 或单钻 DB
+npx tsx scripts/debug/snapshot.ts task <taskId> --json > .e2e-tmp/apc/observability/snapshot.json
+# 关键字检索 cloud log
+npx tsx scripts/debug/logs.ts --contains=<taskId> --since=1h > .e2e-tmp/apc/observability/logs.md
+```
+
+### 4. 判异常（副作用为准，不猜）
+
+| 观察到的副作用 | 判定 |
+| --- | --- |
+| `recent errors` 有 `level:error`（非预期的一次性 warn）· pod crash/pending 超时 · task 卡 `running` 超 reaper 阈值无心跳 · daemon `/healthz` 不应答 | **异常** → 第 4 步开 bug task |
+| 全绿：无 error 级、pods running、tasks 正常流转、daemon 健康 | **healthy** → 报绿，**不开 task**，停手 |
+| 单条 flaky/预期内 warn（如 `[K8sSandbox] pod-status: read failed` 这类已知噪声） | **非异常**——记一句备注，不开 task（造假 bug 比漏报危害大） |
+
+canonical query 的服务端 `partial=false` 不等于生产证据 gate 已满足，更不等于“事实必然完整”；
+`confidenceBoundary.partial=true`、`truncated=true` 或生产 retained gate 不满足时，结论置信边界必须显式
+收窄，自动巡检不得据此判 healthy。
+
+> 拿不准是不是真异常 → 单钻确认（`snapshot`/`logs`），**证据不足不开 task**。开一个假 bug 会污染 bugfix 循环。
+
+### 5. 异常 → 开 bug task（带证据回流 1b）
+
+```bash
+cloud task create \
+  --title "[observability] <一句话症状: pod X crash / task Y stuck>" \
+  --description "Anomaly from periodic sweep.
+Target: <pod|task|workspace>:<id>
+Evidence: <recent-errors 摘要 / bundle 关键段 / asset:<id>>
+Repro: npx tsx scripts/debug/bundle.ts <entity> <id> --stdout" \
+  --kind work_item --priority high --json
+```
+
+抓返回的 `id`（`--json` 里 `data.id`，或人读 `ID:` 行）——这条真 task 行是本 skill 的产出 oracle。可选：`cloud asset upload .e2e-tmp/apc/observability/bundle.json` 拿 `asset:<id>` 挂进 description 作持久证据。
+
+### 6. 回读确认落库
+
+```bash
+cloud task list --json | grep <newTaskId>   # 或 cloud task get <id>
+```
+
+确认 bug task 真行存在、`kind=work_item`、带证据。
+
+## 输出契约（机器判据按这个复验，别自由发挥格式）
+
+旧判据是「正文里出现过 `pod`/`task`/`error` 加个数字」的关键词匹配——**一篇没跑过任何命令的报告照样满分**，而且**只扫了 pods 就宣布全绿**也照绿（其余四面静默跳过，判据看不出来）。现在**五个信号面各占一行**、由 `dimension-coverage` 逐面复核：**某一面没写这行 = 判红**，正文里出现那个词**不算数**。
+
+每行的答案二选一：① 指向**你这轮真落盘的巡检产物**里的那一行（repo-relative `path:line`，判据把该行读回磁盘，文件不存在 / 行号越界 / 空行 → 判红）；② 显式 `N/A — <理由 ≥20 非空白字符>`（这一面本轮**确实**扫不到，比如没有 daemon 可达）。
+
+```
+- SIGNAL-pods: .e2e-tmp/apc/observability/inventory.md:12
+- SIGNAL-workspaces: .e2e-tmp/apc/observability/inventory.md:21
+- SIGNAL-tasks: .e2e-tmp/apc/observability/inventory.md:34
+- SIGNAL-errors: .e2e-tmp/apc/observability/inventory.md:47
+- SIGNAL-daemon: N/A — 本轮 --env=local 无在跑的 sandbox pod，daemon /healthz 无可探测目标
+```
+
+**行号照抄 `cat -n` / `rg -n` 你自己那份产物的真实输出**，不许凭印象写。引用必须 **repo-root-relative**（`/tmp/...` 与绝对路径一律判红——这也是上面要求产物落 `.e2e-tmp/` 的原因）。**报告前不要删产物**：判据是在你跑完之后才读盘的。
+
+> **产物存成可引用的扩展名**：引用解析器只认固定后缀集（`ts/tsx/js/jsx/mjs/cjs/prisma/sql/md/json/sh/py/yml/yaml`）——所以人读产物存 `.md`、机器产物存 `.json`。存成 `.txt` / `.log` **引用不会被解析**，那一面会被判成"没给可复核证据"。
+
+> 这条判据管的是「**每一面都被显式判过**」，不替代下面的异常/healthy 判定——它挡的是**静默漏扫**（只看了一面就宣布全绿），不是替你判异常。
+
+## 产出（副作用 oracle，报告里必须给）
+
+1. **debug 切片真产物**：inventory/bundle/snapshot/logs 的结构化输出（含 recent errors / pod 状态 / task 终态字段）——不是"我看了一下感觉没事"。
+2. **canonical Admin receipt**：capabilities + logs query 输出必须包含 contract digest、principal、requestId、`attemptedSourceTiers`、`availableSourceTiers`、逐 source outcome、coverage/partial/truncated、production retained gate、redaction ruleset 和 evidence hash；默认置信边界不完整的命令退出码必须为 `3`。
+3. **异常路径**：`cloud task create --kind work_item` 返回的**真 task id** + 回读的 task 行（`kind=work_item`）+ description 里的证据 ref（target id / asset）。
+4. **healthy 路径**：明确"无异常、未开 task"，附巡检覆盖了哪些目标（pods/tasks/errors 计数）作为扫过的证明。
+
+**不许**：healthy 时凭空造 bug task（假阳）· bug task 无证据 ref（空口判红）· 断言聊天文本而非真 task 行 · 拿旧 bundle 当本轮证据 · 把已知噪声 warn 当异常刷 task · **把巡检产物写进 `/tmp` 或跑完就删**（证据必须留到判据读盘之后）· 只扫一两个信号面就宣布全绿（五面各自一行，缺一行判红）。
+
+<!-- APC-ACK:v1 -->
+
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+
+执行本 skill 的**第一步**，先落一条调用回执：
+
+```bash
+cloud skill ack observability --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/observability/skill.json

@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "slug": "observability",
+  "name": "Observability Sweep",
+  "description": "Periodic health sweep through the canonical read-only Admin v1 logs contract plus the debug pipeline. Partial evidence is never treated as healthy; a real anomaly opens one evidence-backed work item and a healthy sweep opens none.",
+  "category": "observability",
+  "version": "1.3.0",
+  "license": "MIT",
+  "compatibility": ["claude-code", "prismer-sdk"],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": ["node"],
+      "capabilities": ["admin.logs.read", "prismer.task.create"]
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Sweep the system, distinguish complete from partial evidence, and open a bug only for a real anomaly",
+      "prompt": "Run the observability skill from the repository root. First ACK the skill. Call `npx tsx scripts/debug/admin-observability.ts capabilities`, then query `logs --target-kind=service --target-id=prismer-cloud --since=15m --purpose=periodic-apc-observability-sweep --completeness=require-complete`. For sandbox or daemon evidence, first call `cloud admin log-targets --kind sandbox|daemon --purpose <reason>` and use the returned logical id; never guess a Pod, namespace, or selector. This client must use only canonical Admin v1 read endpoints through the daemon-held credential. Exit 3 from the strict script or exit 2 from `cloud admin logs` means the confidence boundary is partial and must never be reported healthy. SLS offset continuation is best-effort and never proves stable completeness. Never pass or print an API key, run `env`/`printenv`, enable shell tracing, or persist Authorization data. Return an opaque nextCursor unchanged as `--cursor=<opaque>`; never parse or synthesize it. attemptedSourceTiers reports attempts only; availableSourceTiers reports available evidence. In production require-complete, retained evidence must be available, stable, complete, untruncated, and non-duplicating, with productionRetainedRequirement.satisfied=true. Then run `scripts/debug/inventory.ts`, persist the current output under `.e2e-tmp/apc/observability/`, and explicitly adjudicate pods, workspaces, tasks, errors, and daemon. Drill into any suspect with snapshot/bundle/logs. Cite current repo-relative evidence lines for every signal face. Open a `work_item` only for an evidence-backed anomaly and read the task back; otherwise report healthy and open no task. The final report must include contractDigest, principal, requestId, attemptedSourceTiers, availableSourceTiers, per-source outcomes, coverage, partial/truncated, production retained confidence gate, redaction ruleset, evidenceHash, and an explicit confidence boundary.",
+      "expectedArtifacts": [
+        "canonical capabilities and logs-query receipts with contract/principal/request/source/coverage/redaction/evidence metadata",
+        "inventory output persisted at `.e2e-tmp/apc/observability/inventory.md`",
+        "five keyed SIGNAL-pods/workspaces/tasks/errors/daemon lines, each with a current repo-relative citation or explicit N/A reason",
+        "drill-down side-effect slice for every suspect",
+        "explicit anomaly, healthy, or partial-evidence verdict grounded in side effects",
+        "anomaly path: a read-back work_item with evidence; healthy path: explicit no-task statement"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "used canonical Admin v1 discovery and logs query",
+          "match": "(admin-observability|/api/admin/v1/capabilities|logs:query|contractDigest)",
+          "type": "regex",
+          "required": true
+        },
+        {
+          "label": "reports completeness and the confidence boundary",
+          "match": "(require-complete|partial|attemptedSourceTiers|availableSourceTiers|productionRetainedRequirement|coverage|confidence)",
+          "type": "regex",
+          "required": true
+        },
+        {
+          "label": "ran the broader debug pipeline",
+          "match": "(inventory|debug/bundle|debug/snapshot|debug/logs|scripts/debug)",
+          "type": "regex",
+          "required": true
+        },
+        {
+          "label": "every signal face was adjudicated from current evidence or explicit N/A",
+          "type": "structured",
+          "checker": "dimension-coverage",
+          "args": {
+            "dimensions": [
+              "SIGNAL-pods",
+              "SIGNAL-workspaces",
+              "SIGNAL-tasks",
+              "SIGNAL-errors",
+              "SIGNAL-daemon"
+            ],
+            "minReasonChars": 20
+          },
+          "match": "<structured:dimension-coverage>",
+          "required": true
+        },
+        {
+          "label": "made an explicit anomaly, healthy, or partial-evidence decision",
+          "match": "(anomal|healthy|partial|无异常|异常|不完整)",
+          "type": "regex",
+          "required": true
+        },
+        {
+          "label": "grounded the verdict in side effects",
+          "match": "(source|error|pod status|terminal|heartbeat|daemon|snapshot|bundle|副作用)",
+          "type": "regex",
+          "required": true
+        },
+        {
+          "label": "does not fabricate a bug on a healthy sweep",
+          "match": "(no task|healthy.*no|不开|未开|无异常)",
+          "type": "regex",
+          "required": false
+        },
+        {
+          "label": "anomaly path creates a work item with evidence",
+          "match": "(work_item|bug task|task create|task id|evidence|asset:)",
+          "type": "regex",
+          "required": false
+        }
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": [
+      "local-filesystem",
+      "workspace-tasks",
+      "admin-v1-read-endpoints",
+      "admin-debug-endpoints"
+    ],
+    "humanApprovalRequiredFor": [
+      "test/prod sweeps require platform-held admin credentials that are never injected into a coding-agent workdir or command line"
+    ]
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/acs/admin-control-plane-redesign.md",
+      "scripts/debug/admin-observability.ts",
+      "scripts/debug/inventory.ts",
+      "scripts/debug/bundle.ts",
+      "sdk/cloud/src/commands/task.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-08-29T00:00:00Z"
+  }
+}