spec-intake

spec-intake

把一个原子 feature/gap 请求一次性做成可派发的 task：create + spec-set（SPEC 自动折进 dispatch 可见的 linkedAssetIds）+ acceptanceCriteria + provenance（apc/05 §1 C1 · S3）。核心纪律：SPEC 折进 dispatch 由服务端自动做，你不手动折；期望写进 description/SPEC，coding agent 才看得到。

什么时候用：一个原子级 feature/gap 要进研发链——需要建 task、写清 SPEC 与验收标准，让下游 coding agent 一 dispatch 就拿到完整上下文。

承重约束（先记死）

• 原子级 only：S3 是"一个 gap → 一个 task"。请求里裹了两个及以上独立 feature（epic）→ 拒绝，不许 silently 拆。epic 拆分/依赖排序不在本 skill，交人先拆。
• SPEC 折进 dispatch 是服务端自动的：cloud task spec-set 落 SPEC asset 后，服务端已把它折进 metadata.assets.linkedAssetIds（task-spec.service.ts C1/S3）。你不要再 cloud task meta set 手动折 SPEC——那会重复且可能覆盖兄弟键。
• 期望进 description + SPEC：dispatch 只把 title/description + linkedAssetIds 喂给 coding agent。验收期望要么写进 description，要么写进 SPEC（会被折进 linkedAssetIds），否则 agent 看不到。
• provenance 用 --set-string：sha / id 用 --set 会被推断成 number（全数字 sha 精度毁）。写 sha 一律 --set-string。
• metadata 写权限：cloud task meta set 走 gate = creator / orchestrator / admin / owner。spec-intake 是 intake 步、由主 agent 跑，主 agent 建的 task 天然是 creator——所以能写。assignee 不在内。

工具契约（签名以此为准，先核后用）

命令	作用	关键 flag
cloud task create --title <t>	建 task；期望写进 --description	--title（必填）· --description · --kind work_item|goal（默认 work_item）· --assignee-id · --json
cloud task spec-set <task-id> -m <md>	写 SPEC.md（服务端自动折进 linkedAssetIds）	-m/--markdown 或 -f/--file（内容源） · --json
cloud task add-criterion <task-id> --mode <m> --expectation <md>	加一条验收标准	--mode qualitative|quantitative|agent-self-check|manual（必填）· --expectation（必填）· --optional · --json
cloud task acceptance <task-id>	读回验收标准 + 汇总状态	--json
cloud task get <task-id>	读回 task（含 metadata）	--json
cloud task meta set <task-id> --set-string k=v	写 provenance（非 SPEC 的 id / sha）	--set-string（值恒字符串）

• --kind 合法值恰好两个：work_item（默认，可派发工作项）| goal（长期目标投影）。intake 用 work_item。
• --mode 合法值恰好四个：qualitative | quantitative | agent-self-check | manual。
• 各命令 --json 下 stdout 是结构化响应；成功退出码 0，失败非零。

Procedure

0. 先判：是不是原子请求？

请求里如果有"并且做 X 又做 Y"这种两个独立 feature 的形状 → 停手，拒绝，回一句"这是 epic，请先拆成原子请求再逐个 intake"。不要建一个塞两件事的 task，也不要偷偷建两个 task。

1. 建 task（期望写进 description）

cloud task create \
  --title "feat: 一句话需求" \
  --description "期望/验收要点写这里，coding agent dispatch 时看得到。" \
  --kind work_item --json > /tmp/task.json

从 stdout 取 data.id（下称 $TID）。

2. 写 SPEC（服务端自动折进 linkedAssetIds）

cloud task spec-set "$TID" -m "# SPEC

## 目标
...

## 验收标准
- ...
" --json

不要再手动 meta set 折 SPEC——spec-set 已经把 SPEC asset id 折进 metadata.assets.linkedAssetIds 了。

3. 加验收标准（每条一个 criterion）

cloud task add-criterion "$TID" \
  --mode qualitative \
  --expectation "done 长这样：<可判定的验收点>" --json

按需要加多条。verifier 具体方法（怎么验）留给下游，这里只钉 qualitative/quantitative 的期望。

4. 写 provenance（非 SPEC 的 id / sha，用 --set-string）

cloud task meta set "$TID" \
  --set-string intake.sourceSha="$SOURCE_SHA" \
  --set-string intake.gapRef="apc/05 C1"

--set-string 保证 sha 落库是字符串（全数字 sha 不被数字化）。

5. 读回确认（副作用 oracle）

cloud task get "$TID" --json          # 看 metadata.assets.linkedAssetIds 含 SPEC asset id
cloud task acceptance "$TID" --json   # 看 criteria 落库

输出契约（机器判据按这个回读，别自由发挥格式）

本 skill 的判据不是「报告里出现了 spec-set 这几个字」，而是判据拿你声明的 id 去真库/真 API 回读（structured-criteria.ts 的 declared-id-readback）。apc/12 §0.6 记了实证：一份一条 cloud 命令都没跑的编造报告，在旧文本判据下 5/5 全绿。所以报告必须带下面这几类可机器解析的行：

TASK: <cloud task create 返回的 task id>
ASSET: <已在 metadata.assets.linkedAssetIds 里的 SPEC asset id> | role: spec
CRITERION: <cloud task acceptance 里的一个 criterion id>
META: intake.sourceSha = <你写进去的值> | type: string

判据会判红的情况（任一）：

• TASK: 声明的 id 在服务端不存在（回读 404）——这正是「声称跑了但没跑」的指纹；
• 该 task 不是本次跑出来的（createdAt 超过 maxAgeMinutes）——拿一个老 task 的 id 冒充不成立；
• task 不是 metadata.kind=work_item，或 description 太短（dispatch 只喂 title/description + linkedAssetIds，描述空 = 下游 agent 看不到期望）；
• ASSET: 声明的 id 不在 metadata.assets.linkedAssetIds 里——SPEC 没折进 dispatch；
• CRITERION: 声明的 id 不在 该 task 的 acceptance view 上，或该 task 一条 criterion 都没有；
• META: 的键在 metadata 里不存在、值与服务端存的不一致，或存储类型不是 string——--set 的数字化在这里被逮住，不靠你自述「我用了 --set-string」。

回读凭据缺失（无 APC_READBACK_TOKEN / DEV_JWT / PRISMER_API_KEY）或 API 不可达 ⇒ 判红。「验不了」永远不算过。

⚠️ 回读凭据必须与真正跑命令的那个身份一致。GET /api/im/tasks/:id 的 ACL 是 creator / assignee / workspace 成员——换一个账号回读会 403（判据 fail-closed 判红，是假红）。实测踩过：cloud CLI 优先读 ~/.prismer/config.toml 的 api_key（先于 PRISMER_API_KEY env），于是 task 建在 A 账号名下、回读用 B 账号的 JWT ⇒ 403。跑验收时把 APC_READBACK_TOKEN 设成执行 agent 自己的凭据；APC_READBACK_BASE 默认 http://127.0.0.1:3000。

这些 id 必须从命令输出里原样复制，不要重打、不要凭记忆写——回读比对的是字节。

产出（副作用 oracle，报告里必须给）

1. task 真建：cloud task create 的 data.id + cloud task get 读回。
2. SPEC 折进 dispatch：cloud task get --json 的 metadata.assets.linkedAssetIds 含 SPEC asset id（服务端自动折的，不是本 skill 手动折）。
3. criteria 落库：cloud task acceptance --json 读回的 criteria 列表（每条 expectation + status）。
4. provenance 落库：metadata.intake.sourceSha 是字符串（读回确认，全数字 sha 也不被数字化）。
5. epic 拒绝：两部分请求下，未建 task（或明确拒绝）——不 silently 拆。

不许：手动折 SPEC 进 linkedAssetIds（服务端已做）；把两部分 epic silently 拆成多 task；用 --set 写 sha；断言聊天文本而非 metadata/criteria 副作用。

诚实边界

• 判据的能力上界：回读证明的是「这些 id 真在库里、关系真成立、类型真对」。它不证明 SPEC 内容质量，也不能证明「两部分 epic 被拒」——「什么都没建」是缺失，回读不了，那一条至今仍是文本判据（apc/12 §0.6 记录的残余空洞，不得声称已闭合）。
• spec-intake 只承接原子级需求（apc/05 §1 C1 诚实边界）。epic 分解需先经人拆分。
• spec-set 会服务端给 task 落 metadata.devEntryApprovalRequired=true（apc/03 §1「需求进入开发」门，服务端 task-spec.service.ts 自动，非你手动写）。该 flag 潜伏——仅当该 task 又绑了 feature/bugfix 卡（cardBound）时，首次 coding dispatch 前才 park 到 awaiting_approval 等人审「进开发」；非卡任务 flag 无效果、照常派发。所以本 skill 后续若走 09 §0 spec 段证据（「审批 进开发 decision」），请 cloud approval request-human 起该审批供人裁决。
• 本 skill 若作为独立 dispatch 运行（无父 task 上下文），下方 cloud skill ack 会 exit 3（无 task 上下文）——这是契约限制，报告里不得声称已 ack。它建的 task 是产物，不是它自己的 dispatch task。

调用回执（APC 平台方运营纪律 · 自动注入，勿手改）

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

cloud skill ack spec-intake --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 诚实标注）。