# 外部同步回写校验细则

> 本文件是 `/kb-propose`、`/kb-archive`、`/kb-verify-issue` 外部 sync 步骤的**幂等与主 Agent 复核**约定。  
> 事件与 dispatcher 见 [kb-external-sync.md](kb-external-sync.md)。具体 provider API 由扩展插件文档说明，**不在 marketplace 源仓内置**。

## 1. 通用原则

1. 子 Agent 回报「外部 sync 已完成」后，主 Agent / orchestrator 必须用 **shell 读磁盘**（如 `cat …/00-manifest.json`）复核对应字段，**不得**仅凭 IDE Read 或口头成功就重派或自行补跑 provider。
2. 磁盘幂等键已满足时，**禁止**重复登记或重复发通知。
3. 子 Agent sync 成功但 manifest 未落盘：重派子 Agent **仅补写** manifest 与相关 Markdown 头部，**禁止**主 Agent 自行重跑 provider。

## 2. `/kb-propose`（registry / notify）

| 条件 | 动作 |
|------|------|
| 无 `external.registry_record_id` | 可执行 `registry.propose` / `notify.propose_created` |
| 已有 `registry_record_id` | **跳过**外部登记；向用户汇报已有链接 |
| `notified_events` 已含 `"created"` | **跳过** `notify.propose_created` |

## 3. `/kb-archive`（sync.archive_completed）

| 条件 | 动作 |
|------|------|
| 有 `registry_record_id` 且 `notified_events` 不含 `"completed"` | commit+push **之后**执行 `sync.archive_completed` |
| `notified_events` 已含 `"completed"` | **跳过** sync；禁止重复通知 |
| 未启用 `integrations` | **跳过**步骤 10，不阻断归档 |

`notified_events` 的 `"completed"` 仅表示 KB archive 外部 sync 步骤已执行，**不等于**外部系统终态。

## 4. `/kb-verify-issue`（registry / sync）

| 条件 | 动作 |
|------|------|
| 本轮（`round` 最大）`notified === true` | **跳过** `sync.verify_issue` |
| 本轮 `notify_attempted === true` 且 `notified` 非 `true` | 通知结果不确定，**禁止**自动重发；仅用户确认未收到后可补发一次 |

Webhook/通知成功后须**同轮**写盘 `notified: true`。

## 5. Provider 脚本契约（扩展插件须实现）

handler 脚本由 `kb-external-sync.mjs` 以如下参数调用：

```bash
node <handler> --event <event> --scan-id <14位前缀> [--round N] [自定义参数...]
```

- 退出码 `0` 表示成功；非 0 表示失败（dispatcher 向上传递）。
- 成功时须同轮更新 `00-manifest.json` 的 `external` 与相关 Markdown 头部（字段名见 kb-external-sync.md §4）。
- 未配置或不应执行时，provider 可自行退出 0 并说明 SKIP（dispatcher 在未启用 integration 时已 SKIP，provider 内通常无需再判）。