feat: support repository-owned PR finish providers (#318)

* feat(native): support repository-owned PR finish providers

* fix(native): harden pull request finish providers

* test(native): harden pull request finish assertions

* fix(native): retain PR URL after final verification failures

---------

Co-authored-by: zhenyu.jiang <jiangzhenyu@keyfil.com>

Author: LDmoxeii

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.4.0-beta.20] - 2026-08-16
+
+### Added
+
+- **Repository-owned Native pull-request finish providers**: Projects can opt into a structured repository command for PR title, body, template, and policy validation while Comet retains commit, push, remote base/head/SHA verification, existing-PR reuse, recoverable failure state, and safe worktree cleanup.
+
 ## What's Changed [0.4.0-beta.19] - 2026-08-15
 
 ### Changed

README-zh.md

@@ -560,6 +560,19 @@ Native 可以同时保留多个 active change；`comet status` 会分别列出
 
 `comet-state.yaml` 和 `.comet/runtime/native/` 中的机器状态由 Runtime 管理。需求改变时修改 brief 或拟议规格，Runtime 会回到 Shape；实现改变时回到 Build，再由新的 Verifier 验收。不要手改状态来跳过阶段。
 
+当仓库要求使用自有 PR 模板或校验脚本时，可在 `.comet/config.yaml` 中显式配置 Native 的仓库命令 provider：
+
+```yaml
+native:
+  finish:
+    pull_request:
+      provider: repository-command
+      command: [pwsh, -NoProfile, -File, scripts/comet-create-pr.ps1]
+      timeout_ms: 120000
+```
+
+选择 Archive 的 `pull-request` 收尾后，Comet 仍负责提交、推送、观察已有 PR、核对 base/head/head SHA、幂等恢复和安全清理；仓库命令只负责标题、正文、模板及仓库特有的远端校验。命令的可执行文件必须是 PATH 中的裸名称或项目内相对路径；它在项目根目录执行，通过 stdin 接收 `comet.native.pull-request-finish-input.v1` JSON，并必须在 stdout 返回 `comet.native.pull-request-finish-result.v1` JSON。即使使用 repository-command，仍须安装并认证 GitHub CLI (`gh`)，因为 Comet 会调用 `gh pr list` 和 `gh pr view` 独立核验远端状态。未配置时继续使用兼容的 `gh pr create --fill` 行为。
+
 </details>
 
 <details>

README.md

@@ -593,6 +593,19 @@ Native can keep multiple active changes at the same time. `comet status` lists t
 
 Runtime owns `comet-state.yaml` and machine state under `.comet/runtime/native/`. Requirement edits return the change to Shape; implementation edits return it to Build before a fresh Verifier reviews the candidate. Do not hand-edit state to skip a phase.
 
+Repositories that require their own PR template or validation script can opt into a Native repository-command provider in `.comet/config.yaml`:
+
+```yaml
+native:
+  finish:
+    pull_request:
+      provider: repository-command
+      command: [pwsh, -NoProfile, -File, scripts/comet-create-pr.ps1]
+      timeout_ms: 120000
+```
+
+After a `pull-request` Archive finish is selected, Comet still owns commit, push, existing-PR observation, base/head/head-SHA verification, idempotent recovery, and safe cleanup. The repository command owns only title/body/template policy and repository-specific remote validation. Its executable must be either a bare name resolved through PATH or a project-relative path. It runs from the project root, receives `comet.native.pull-request-finish-input.v1` JSON on stdin, and must return `comet.native.pull-request-finish-result.v1` JSON on stdout. GitHub CLI (`gh`) must still be installed and authenticated because Comet independently verifies remote state with `gh pr list` and `gh pr view`. Projects without this configuration keep the compatible `gh pr create --fill` behavior.
+
 </details>
 
 <details>

assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.0-beta.19",
+  "version": "0.4.0-beta.20",
   "skills": [
     "comet/SKILL.md",
     "comet/agents/openai.yaml",