Open Source Ops — 外部 PR/issue 操作

SOP 位置: 本 skill 是 thread-orchestration 在社区守门/外部 PR 场景下的子 workflow。 上一步: thread-orchestration（分发） | 下一步: request-review / receive-review / merge-gate

核心原则

1. Server 不替你猜：F128 proposal runtime 不再推断 PR identity、作者角色、主仓采纳策略或任何实例私有同步策略。这些判断必须在拥有 cwd / provider / provenance 上下文的 child-side 完成。
2. Child thread 自己 grounding：进入子 thread 后，第一只猫必须显式加载本 skill，用 deployment 的 provider adapter（例如 GitHub 用 gh）把外部对象落到可验证的事实字段。
3. 外部作者优先负责修复：默认把 finding 路由给外部作者；本地猫替作者改代码需要显式授权与 provenance。
4. 反向溯源 fail-closed：proposal source、projectPath、preferredCats、initialMessage 里的 URL 都不能直接当 origin 证据；必须有独立的 provider 级验证与内部 provenance 搜索。

进入条件

在 child thread 中看到以下信号时加载本 skill：

• title / reason / initialMessage 出现外部 PR/issue URL 或 owner/repo#NNN 简写。
• 任务明确是 review / triage / intake / advisory 之一。
• 需要与外部作者、CI、maintainer 交互。

Step 1: Grounding（落地 provider-neutral subject 与 author）

必须在动手判断之前完成。使用当前 deployment 的 provider adapter（例如 GitHub 场景用 gh）查询外部对象，产出以下事实字段；禁止从 thread title/reason 直接反推这些字段而不验证。

Fail-closed 分支：

• verifiedAuthorIdentity 是 bot / shared account / 无法解析 → 明确停住，标记 author_kind: ambiguous，不继续 custody 判断，直到 operator 或 maintainer 显式确认。
• authenticatedContributorIdentity 无法解析 → 按 null 处理，authenticatedRole 降级为 outsider。仅当工作流需要 mutating custody（review publication / merge / verdict）时才必须停住重新认证；纯 advisory / triage 审计可在匿名 outsider 角色下继续。
• provider 查询失败（无网络、无权限、对象不存在）→ 停住，输出 unknown。

Step 2: 身份与 custody 判断（fail-closed）

custody 只看 verified author 与 当前 authenticated contributor identity 是否匹配，以及 当前 identity 的权限角色，不看仓库名字：

Fail-closed 分支：

• bot/shared/ambiguous author → 停住，不分配 custody。
• authenticatedRole 与 authorship 冲突（例如 identity match 但当前账号无写权限）→ 按 contributor 处理，禁止以 maintainer 身份 self-review / self-merge。
• maintainer capability（merge 权限）必须与 authorship 分离：能 merge 不等于就是作者，是作者不等于能 merge。

本地猫接管 fix 的授权：只有当外部作者无响应、修复是 trivial blocker、且有 operator 或 maintainer 显式授权时，本地猫才接管 fix。授权必须在 thread 中留下可引用的消息，并记录 provenance。

Step 3: Maintainer 五问（仓库中立版）

把五问抽象成任何外部仓库都可以用的 adoption 框架：

1. 问题与设计差距：它解决什么问题？当前方案与项目现有设计/契约的差距在哪？
2. Vision/contracts fit：它是否符合项目方向、semver 契约、架构原则？是否引入反模式？
3. 是否 adopt：基于前两条，给出 adopt / reject / advisory-only 的明确结论。
4. Adopt 后的路径：merge-as-is / redesign / reimplement / port — 哪一种是风险最小的终态？
5. Custody 边界：谁负责修、谁负责 review、谁负责 merge、谁负责后续回归测试 / 文档 / 同步？

回答必须引用 grounding 步骤中的具体字段（verifiedAuthorIdentity、providerSubject.headSha、authenticatedRole 等），不能只给主观结论。

Source-to-public publishing

当一个仓库是真相源、另一个仓库是公开分发面时，把同步和发版当作两个独立状态迁移。这里定义的是可移植边界；具体 exporter、ledger、gate 与 tag 命令仍以当前 deployment 的真相源为准。

D: Outbound Sync

1. 先核清 public main 上的社区改动与 source ownership，再冻结 exact source revision、exact public base 和 reconciliation evidence；冻结后的新提交进入下一班。
2. 同一 source cut 只跑一次所选 source gate。已有写授权时，由 canonical writer 持有唯一 candidate-public validation；尚无写授权时，停在 no-write validate / write handoff。
3. writer 只能从已冻结的 public base 生成候选内容，公共落地仍走可审查的 PR，并记录 source/public provenance。
4. 未合入的外部 PR 本身不会被 writer 改写；只有明确的同车约束、已落 public delta 或候选行为冲突，才构成同步阻塞。

G: Public Release

1. 给当前稳定 public main 发版时，绑定 exact public HEAD 与最近一次可信 sync provenance；不要为了制造发版证据而伪造新的 source export。
2. release 只验证其明确承诺的分发物；没有承诺安装包时，零二进制资产可以是正确终态。
3. 若一次 outbound sync 同时有明确 release intent，则让 release 引用该已落 public cut；同步与发版的 terminal 仍分别记录。

Sync ≠ Release：outbound sync 更新公开分支，public release 给一个已经验证的公开状态打稳定承诺。前者完成不自动证明后者完成，后者也不要求凭空重跑前者。

Step 4: 反向溯源（reverse provenance）

进入本 thread 的 proposal 可能带有一段 initialMessage 或 reason，里面提到外部对象。这些信息只能算线索，不能算证据。外部 provider subject 的验证（Step 1）已经给出“这是哪个外部对象”；内部 provenance 回答“这个 thread 从哪个内部上下文来、与外部对象是什么关系”。二者必须分开。

内部 provenance 搜索

用现有 project/thread evidence 能力验证这个 child thread 的内部来源：

1. 读取 child thread 的 createdFromProposalId / sourceThreadId。
2. 用 cat_cafe_get_thread_context 读取源 thread 的 proposal card 与源消息。
3. 用 cat_cafe_search_evidence 在 project/thread evidence 中搜索显式的外部对象 anchor（例如 pr:owner/repo#NNN、commit SHA、proposalId、sourceMessageId）。搜索范围不限于 proposal source thread；相关 thread 也可能被粘贴/引用。
4. 对每一个候选 thread/message，逐项列出它与此 providerSubject 的关系证据；没有显式 anchor 的只算 related 或 unknown。

证据分级

Fail-closed 规则

• 不能把 proposal sourceMessageId、projectPath、preferredCats 当 origin 证据。
• 不能把 "标题写了 clowder-ai#1387" 当已验证；必须跑一次 provider adapter 拿到对象状态，并搜索到内部显式 anchor。
• 仅有相同 PR anchor 不足够判定 origin；必须同时提供 provenance 链证明内部 thread 创建/提出了该外部对象（例如内部 assignment 明确说"向 owner/repo 提 PR #N"，或内部 feature doc/commit 把该 PR 登记为本地交付物）。外部对象触发内部 thread 只能算 related 或 unknown。
• 内部 provenance 与外部对象对不上 → 输出 unknown 并升级到 operator。

记录 verified metadata

当 providerSubject 已在 Step 1 验证后，无论内部 provenance 是 origin、related 还是 unknown，都要调用 cat_cafe_set_thread_metadata 把外部对象与当前 thread 关联起来：

{
  "prs": [{ "repo": "owner/repo", "number": 123 }],
  "issues": [{ "repo": "owner/repo", "number": 456 }]
}

后续 tracking/review/closure 只能在这个 metadata write 之后进行 —— verified provider subject 是写 metadata 的授权条件，不是“必须找到 origin”。

Step 5: 工具落点与协作

Review

• 用 request-review 把 diff 送给非作者猫做独立 review。
• cat_cafe_record_external_review_verdict 只用于 configured maintainer-owned inbound reviews：当前 authenticated identity 是外部仓库的 maintainer，且 PR 作者不是当前 identity（外部贡献者向我们维护的仓库提 PR）。
• 其余场景不写 formal verdict：
  • 我们向外部仓库提的 PR（outbound / self-authored）→ 由外部 maintainer review，我们只回复其 comment / 修自己的 PR，不把 verdict 写回。
  • 第三方仓库的纯审计 → advisory only，只在本 thread 内产出 findings，不强制写回外部系统。
  • 如果需要以 advisory 形式把评论发到外部系统，用 provider adapter（例如 gh pr comment）直接发布，不要用 custody verdict 工具。

Tracking

• 不要为每个 PR/issue 自动注册 tracking。只有以下两类情况才注册显式 typed predicate：
  1. 工作真实阻塞在外部条件（等作者回复、等 CI、等 maintainer review）。
  2. 计划做 formal external review 时，需要先用 cat_cafe_register_pr_tracking seed projection，才能在终端态记录 cat_cafe_record_external_review_verdict。
• 注册只需要给出对象（repoFullName + PR/issue 号）。when、goal、nextStep 都不必填——服务端按角色解析默认受众并生成确定性 continuation；expiresAt 可选，省略则没有时间到期，写了就是一个真实、可见的截止时间。
• 读注册返回里的 notification：它写明实际装了哪些条件、解析出的角色，以及评论面的过滤规则。若 perspective.role 是 unresolved，说明身份/角色没能确定——评论会照常投递但标注「身份/角色未知」，不要把它当成正常覆盖已建立。
• Advisory / triage / 纯审计不需要注册 tracking。

Merge / closure

• 外部 PR 的 merge 只能由有权限的 maintainer 账号执行；本地猫共享 login 不能 self-review / self-merge。
• 合入后是否需要同步 feature doc / BACKLOG 由项目自己的 SOP 决定，本 skill 不做实例私有假设。

Step 6: 回报（reportingMode）

社区守门 / 外部 PR 分发使用 reportingMode: "final-only"：

• 闭环前 0 次过程 cross-post。
• 闭环后 1 次最终总结 cross-post 回主 thread，携带：
  • grounding 结果（providerSubject、verifiedAuthorIdentity、authenticatedRole）
  • 五问结论
  • custody 去向（作者修 / 本地猫显式授权接管 / advisory only）
  • 后续跟踪 registration（如果有）

与相关 Skill 的关系

Common Mistakes