git-ops

git-ops

收口一个本地 coding task 的 git 动作——在 workdir 上 commit / branch / merge / push，并把 branch+sha 落回 task metadata（apc/05 §1 A2 · S8）。核心纪律：merge 冲突绝不自动解决——停手、列出冲突文件、escalate 给人，workdir 保持现场不回滚（apc/00 §3 不变量 6）。

什么时候用：一个 coding task 改完，需要把改动收口成 commit / 分支、merge 回主线、并把 provenance（branch/sha）记到 task 上。

承重约束（先记死）

• commit 不自动 stage：cloud git commit 只提交已 staged 的内容。你必须先自己 git add <task-owned files>，只 stage 本 task 拥有的文件，别把无关改动带进去。
• 单任务串行不变量：同一 repo 同时只有一个 coding task 在飞。别假设并发安全。
• prod tag 禁止：四个 prod 触发前缀（k8s-prod-* / desktop-prod-* / prod-* / ali-k8s-prod-*）的 tag push 被 daemon 拒（真闸是 GitLab protected tags）。
• push 只到 bare 替身：remote 必须是 daemon allowlist 里的纯名字（默认 origin，本地指向 bare 替身）；URL / 带 -- 的值一律被拒。无 --force。
• provenance 写 metadata 要用 --set-string：sha / branch 是字符串，用 --set（推断 JSON）会把全数字 sha 变成 number（40 位 sha 会被 1.2e+39 精度毁掉，7 位全数字 sha ≈3.7% 概率）。

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

cloud git 的 cwd 永远不由你传——它从 --workdir <id> 指向的 IMWorkdir 行读，daemon 侧再 jail 一次。--workspace / --daemon 默认取 dispatch env（PRISMER_WORKSPACE_ID / PRISMER_DAEMON_ID）。

命令	作用	关键 flag
cloud git workdirs	列 workspace 里的 repo workdir（拿 <workdirId>）	--workspace --json
cloud git commit <workdirId> -m <msg>	提交已 staged 的改动	-m/--message（必填）
cloud git branch <workdirId> --name <b>	建并切到新分支	--name（必填）
cloud git merge <workdirId> --source <ref>	把 <ref> merge 进当前分支（冲突→escalate，绝不自动解决）	--source（必填）
cloud git push <workdirId> --branch <b> | --tag <t>	push HEAD 到分支，或 push tag（prod tag 被拒）	--branch 或 --tag（二选一）· --remote（allowlist 纯名字，默认 origin）
cloud task meta set <task-id> --set-string k=v	把 provenance 写进 task metadata	--set-string（值恒字符串）

• 退出码：成功 0；失败非零。--json 下 stdout 是结构化 {ok, op, sha?, ref?, cwd, ...}（成功）或 {ok:false, op, code, message, files}（失败）。
• code:'conflict' 是冲突信号，files[] 是未合并文件清单——这是承重的 escalation payload。
• 权限：cloud task meta set 走 metadata gate = creator / orchestrator / admin / owner，assignee 不在内。写 provenance 这一步必须以主 agent（orchestrator/creator）身份跑——coding agent 自写会被 403。

Procedure

1. 定位 workdir

cloud git workdirs --workspace "$PRISMER_WORKSPACE_ID" --json

从返回里挑本 task 对应的 repo workdir id（下称 $WD）。

2. Stage 本 task 拥有的文件（自己做，commit 不代劳）

# 在 workdir 的 repo cwd 里，只 stage 本 task 改的文件
git add path/to/file-a path/to/file-b
git status --short   # 确认只 stage 了 task-owned 文件

3. Commit

cloud git commit "$WD" -m "feat(x): 一句话说清这次改动" --json

从 stdout 的 sha 字段取真 commit sha（下称 $SHA）。

4. Branch（可选，按 task 需要建 scoped 分支）

cloud git branch "$WD" --name "feat/task-$PRISMER_TASK_ID" --json

5. Merge 回主线 —— 冲突是停手信号，不是重试信号

cloud git merge "$WD" --source feat/task-xxx --json > /tmp/merge.json; M=$?

• M == 0：merge 成功，取新 HEAD sha。
• M != 0 且 code == "conflict"：停手。读 files[]——那是未合并文件清单。不要 git merge --abort、不要 git reset、不要 -X ours/theirs、不要任何自动解决。把冲突文件清单原样交给人 escalate：

Merge conflict — NOT auto-resolved. Escalate to a human.
Conflicted files (<n>):
  <file-1>
  <file-2>

workdir 保持 daemon 留下的现场（.git/MERGE_HEAD 在、工作区有 <<<<<<< 标记），人可以直接进去看。冲突判据是 git 的副作用（未合并索引 / 进行中的 merge），不是错误文本——所以拼写错误的 ref 不会被误报成冲突。

6. Push（到 bare 替身；prod tag 会被拒）

# 分支：
cloud git push "$WD" --branch feat/task-xxx --json
# tag（非 prod）：
cloud git push "$WD" --tag k8s-test-20260724-v2.0.7 --json

• prod 触发前缀的 tag（k8s-prod-* 等）→ 返回 code:'prod_tag' 非零退出。这是对的，别绕。
• remote 只能是 allowlist 里的纯名字；默认 origin（本地 = bare 替身）。

7. 写 provenance 回 task（以主 agent 身份，用 --set-string）

cloud task meta set "$PRISMER_TASK_ID" \
  --set-string git.branch=feat/task-xxx \
  --set-string git.sha="$SHA"

必须 --set-string：--set git.sha=1234567 会把全数字 sha 变成 number。

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

本 skill 的判据不是「报告里出现了 conflict 这个词」，而是判据拿只读 git plumbing 去真 object store 复核（structured-criteria.ts 的 git-claim-readback），provenance 则回读真 task 行（declared-id-readback）。所以报告必须带这些可机器解析的行：

GIT-REPO: .e2e-tmp/<name>/work
GIT-COMMIT: <full sha> | files: a.txt, b.txt
GIT-BRANCH: <branch> | head: <full sha>
GIT-PUSHED: <branch> | remote: origin
GIT-REFUSED-TAG: k8s-prod-<date>-v<x.y.z> | remote: origin
GIT-CONFLICT-REPO: .e2e-tmp/<name>/conflict
GIT-CONFLICT-FILES: c.txt
TASK: <task id>
META: git.sha = <full sha> | type: string
META: git.branch = <branch> | type: string

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

• GIT-REPO 不在 .e2e-tmp/ 沙箱里，或它解析到打分器自己的仓库根——共享工作树永远不许当演示仓库（判据硬拒，不看措辞）；
• GIT-COMMIT 的 sha 不是该仓库里的 commit 对象；
• 该 commit 的文件集与 files: 声明不等，或包含 task 不拥有的文件——cloud git commit 从不自动 stage，混进来的文件就是你 stage 的；
• GIT-BRANCH 不存在、tip 与 head: 不符、或不含那个 commit；
• GIT-PUSHED 的 remote 不是本地 bare 替身（网络 remote 一律红），或替身上没有那个分支 / sha 不一致；
• GIT-REFUSED-TAG 真的躺在替身上（那就不是被拒，是被推上去了），或那个 tag 根本不匹配 prod 触发前缀（拒一个无害 tag 证明不了任何事）；
• 冲突仓里没有 MERGE_HEAD——merge --abort / reset / -X ours 恰好删掉的就是这份证据，所以「我停手并 escalate 了」不再是可自述的；
• GIT-CONFLICT-FILES 与 git diff --name-only --diff-filter=U 不等（漏报冲突文件也红）；
• META: 的值与服务端存的不一致，或**存储类型不是 string``**（--set` 数字化在这里被逮住）。

这些命令全是只读的（cat-file / show --name-only / rev-parse / ls-remote / diff --diff-filter=U / tag -l）——判据本身绝不写任何仓库。

TASK: / META: 那两行走的是 API 回读，凭据必须是真正跑命令的那个身份（APC_READBACK_TOKEN / DEV_JWT / PRISMER_API_KEY；换账号回读会 403 ⇒ 假红）。凭据缺失或 API 不可达一律判红——「验不了」不算过。

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

1. 真 commit sha / 真 branch ref：取自 cloud git commit/branch/merge 的 sha/ref 字段（--json），可在 workdir 里 git rev-parse / git branch 复核。
2. 冲突态：code:'conflict' + files[] 非空 + workdir 现场保留（.git/MERGE_HEAD 在、工作区含冲突标记、HEAD 未移动）——不是聊天里说"有冲突"。
3. prod tag 被拒：cloud git push --tag <prod-prefix> 非零退出 + code:'prod_tag'。
4. provenance 落库：cloud task meta set --set-string 后 task metadata.git.sha 是字符串（读回确认，全数字 sha 也不被数字化）。

不许：merge 冲突后自动 abort/reset/-X；断言聊天文本而非 git 副作用；用 --set 写 sha；push 到非 allowlist remote 或用 --force；以 assignee 身份写 metadata（会 403）。

诚实边界

• 判据核的是 git 的副作用，不是走了哪条通道：commit 是 cloud git commit 还是（无 workdir-bound daemon 时）scratch repo 里的 git commit 产生的，object store 里长得一样。所以判据不能证明「走了 cloud git」，只能证明「这些 git 事实真存在」。同理 GIT-REFUSED-TAG 证明的是拒绝的效果（tag 不在替身上），不是 daemon 侧那道闸真被触发。
• 「push 不带 --force」判据核不到（remote 上看不出上一次 tip），仍是文本判据——不得声称已闭合。
• cloud git 需要 workdir 绑定的 daemon 在线。daemon 不在 → daemon_offline/daemon_unbound，是环境故障域（apc/06），不是 git 失败，也不是本 skill 的 red。
• commit 不 stage、jail 是词法+realpath（照抄 resolveWorkdirCwd 同款限制）——这些是平台约束，本 skill 不绕。

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

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

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