# CI/CD Branch Follower 退役参考

SPEC: PJ2026-01060703 CI/CD branch follower draft-2026-07-03-p0-branch-follower

## 当前边界

`config/cicd-branch-followers.yaml` 中现有 follower 已全部迁移到 Gitea source authority + CLI 手动 PaC webhook 发布链。`cicd branch-follower` 不再是 delivery authority，只保留退役状态和历史对象的只读诊断。

默认入口只允许：

```bash
bun scripts/cli.ts cicd branch-follower status [--follower <id>]
bun scripts/cli.ts cicd branch-follower events --follower <id>
bun scripts/cli.ts cicd branch-follower logs --follower <id>
bun scripts/cli.ts cicd branch-follower taskrun --follower <id> --taskrun <name>
bun scripts/cli.ts cicd branch-follower runtime --follower <id> --workload <name>
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step state-read
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step controller-source
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step status-read
bun scripts/cli.ts cicd branch-follower debug-step --follower <id> --step decide
```

默认入口不支持 `plan`、`apply`、`run-once`、`job`、`gate`、`state-write` 或 `cleanup-state`。这些动作不得用于推进、补跑或恢复已迁移 consumer。

当前交付状态使用：

```bash
bun scripts/cli.ts cicd status --node <NODE>
bun scripts/cli.ts platform-infra pipelines-as-code status --target <NODE> --consumer <id>
bun scripts/cli.ts platform-infra pipelines-as-code history --target <NODE> --consumer <id> --limit 10
```

## Authority 与配置防绕过

- 写操作只信任仓库内固定 `config/cicd-branch-followers.yaml`。
- `--config` 只可用于只读诊断；任意绝对路径、临时 YAML 或自造 `deliveryAuthority: legacy-manual` 都不能扩大写权限。
- 只有固定 owning YAML 中存在精确 `legacy-manual` follower 时，旧写实现才可从 `legacy-cicd` scope 进入。当前 YAML 没有此类 follower，因此 scoped help 不展示 mutation 示例。
- 非唯一、混合或漂移的 authority 一律 `mutation=false` 并 fail-closed。
- 退役状态清理与交付完全分离；确需删除旧 ConfigMap 状态时，只能使用 `retired-maintenance cleanup-state`，并且仍须固定 owning YAML、显式确认和有界候选输出。

## 只读单步诊断

- `state-read`：读取有界 ConfigMap 状态、resourceVersion 和更新时间。
- `controller-source`：读取退役控制器 checkout 身份与关键文件标记，不执行同步。
- `status-read`：读取 source、Tekton、Argo 和 runtime 状态，不触发 adapter。
- `decide`：只运行 dry-run 决策，不创建对象、不写状态。
- `events|logs|taskrun|runtime`：按单个 follower 或对象渐进披露历史证据。

状态、事件和日志必须保持有界，并优先显示失败、活动和慢 TaskRun、Argo 非健康原因、runtime readiness 与短错误。缺失对象必须显示 `NotFound` 或结构化缺失原因，不得推断成功，也不得输出写入型 `Next`。

## 自动链规则

当前唯一正式链路是：

```text
GitHub PR merge
-> GitHub webhook durable inbox
-> Gitea authority branch + immutable snapshot
-> Gitea webhook
-> Pipelines-as-Code
-> Tekton
-> GitOps/Argo
-> runtime
```

自动链不通时修 owning YAML、webhook bridge、controller 或源码，并用修复 PR 合并产生的新正常事件验收。禁止重新启用 branch-follower controller、Gitea Actions、`act_runner`、host worktree、人工 mirror sync、直接 Gitea push、人工 PipelineRun 或运行面 patch 作为 fallback。

## 历史处置

- `hwlab-jd01-v03`、`agentrun-jd01-v02`、`web-probe-sentinel-master` 及对应 NC01 历史项只用于迁移审计。
- 退役对象的历史 timing、reuse 和 closeout payload 不能作为当前状态权威。
- 需要保留的历史实现留在源码中并由 authority guard 屏蔽；文档不得继续把它描述为当前自动控制器。
