feat: add auth broker p0 skeleton

docs/reference/auth-broker.md

@@ -20,7 +20,8 @@ Artifact registry / deploy 路径的问题不同：D601 registry 是 host loopba
 
 P0 只解决 GitHub REST 权限不应出现在普通 runner env 中的问题：
 
-- 新增一个计划中的 Rust 单二进制服务，工作名 `auth-broker`。
+- 新增 Rust 单二进制服务 skeleton，路径为 `src/components/microservices/auth-broker`，工作名 `auth-broker`。
+- 新增 CLI adapter contract，入口为 `bun scripts/cli.ts auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run`。
 - 先只在 D601 dev 验证，入口只能是 k3s ClusterIP、backend-core/microservice 私有代理或 D601 loopback，不开放公网端口。
 - broker 持有服务端 GitHub 凭证引用并调用 GitHub REST；runner 不接收、不读取、不打印 `GH_TOKEN` / `GITHUB_TOKEN`。
 - API 只接受结构化 operation，不接受 shell、argv、任意 URL 或原始 `gh api`。
@@ -30,6 +31,15 @@ P0 可以让 Code Queue 并行推进，但必须把实现拆成互不冲突的 l
 
 ## API
 
+The first skeleton lives at:
+
+- `src/components/microservices/auth-broker/Cargo.toml`
+- `src/components/microservices/auth-broker/src/main.rs`
+- `src/components/microservices/auth-broker/Dockerfile`
+- `scripts/src/auth-broker.ts`
+
+The skeleton intentionally does not read `GH_TOKEN` or `GITHUB_TOKEN`. It uses only redacted readiness configuration such as `AUTH_BROKER_GITHUB_CONFIGURED`, `AUTH_BROKER_GITHUB_CREDENTIAL_REF`, `AUTH_BROKER_ALLOWED_REPOS` and optional `AUTH_BROKER_AUDIT_LOG`. Real secret mounting is outside this contract.
+
 ### `GET /health`
 
 只返回服务状态和 redacted capability，不返回 secret 值。
@@ -192,6 +202,37 @@ P0 must use stable failure kinds so Code Queue can decide whether to retry, spli
 
 All failures must include `message`, `requestId`, `failureKind`, `degradedReason`, `runnerDisposition`, `retryable`, and a `next` array with bounded diagnostic commands or manual actions. None may include secret values.
 
+## CLI Adapter
+
+The local runner adapter is a dry-run contract surface only:
+
+```bash
+bun scripts/cli.ts auth-broker contract
+bun scripts/cli.ts auth-broker health --dry-run
+bun scripts/cli.ts auth-broker credential-request --operation github.pr.create --repo pikasTech/unidesk --dry-run
+bun scripts/cli.ts auth-broker pr-preflight --repo pikasTech/unidesk --base master --head <head-branch> --issue 59 --dry-run
+```
+
+If no `UNIDESK_AUTH_BROKER_URL` / `AUTH_BROKER_URL` is configured, the adapter returns a structured failure instead of falling through to live GitHub or a shell fallback. `GH_TOKEN` / `GITHUB_TOKEN` presence is reported only as migration diagnostics and does not make the Auth Broker adapter ready:
+
+```json
+{
+  "ok": false,
+  "failureKind": "auth-missing",
+  "degradedReason": "broker-needed",
+  "runnerDisposition": "infra-blocked",
+  "brokerNeeded": true,
+  "tokenCoverage": {
+    "ok": false,
+    "presenceOnly": true,
+    "valuesRead": false,
+    "valuesPrinted": false
+  }
+}
+```
+
+When a broker endpoint is configured, the same command returns the P0 ready shape with `tokenCoverage.source=auth-broker`, `runnerEnvTokenRequired=false`, `valuesPrinted=false`, `preflightCreatesPr=false`, `preflightMergesPr=false` and `brokerProxy.writesRemote=false`. The adapter sanitizes endpoint URLs before printing and never reads token values.
+
 ## D601 Dev Acceptance
 
 The minimum D601 dev verification is: