impact-trace

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. 逐维搜索，收集带行号的命中

# 维度 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 上，把结论上报：

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 平台方运营纪律 · 自动注入，勿手改）

执行本 skill 的第一步，先落一条调用回执：

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 诚实标注）。