@numa-tech/numa 1.14.28 → 1.14.30

package/skills/numa-jenkins-deployment/SKILL.md

@@ -1,147 +1,36 @@
 ---
 name: numa-jenkins-deployment
-description: 使用 Numa CLI 安全规划、执行、监控、诊断和恢复 MCI DevOps/Jenkins 的 v2 platform-build 或旧 v1 pipeline 部署。用户要求部署、发布、上线、重新部署、回滚，或排查 `pipeline platform-build`、`pipeline build/builds/status/log/retry/stop`、Jenkins 构建、GitOps image intent、结果未知、流水线无日志时必须使用。负责区分应用未入驻、Jenkins/branch 未初始化、v2 rollout 未就绪、项目规范失败、构建或运行失败、远端 Flux CAS 已落地但平台账本未决，以及控制面故障。
+description: 使用 Numa CLI 安全规划、执行、监控、诊断和恢复 MCI DevOps/Jenkins canonical Multibranch 流水线部署。用户要求部署、发布、上线、重新部署、回滚，或排查 pipeline build/builds/status/log/retry/stop、Jenkins 构建、GitOps 写入和运行态时必须使用。
 ---
 
 # Numa Jenkins Deployment
 
-把 Numa CLI 当作 Jenkins 和平台 GitOps writer 的唯一受控入口。先判定 delivery mode，再证明应用、源码、Job、binding、rollout、审批与运行态指向同一发布；不要用重复触发掩盖初始化或结果对账问题。
+通过标准 `pipeline build` 表面执行仓库中的 `gitopsBuildEntry()`。已退役的签名快照、独立触发、rollout 和 provenance 命令不得使用；若旧服务仍返回这些 capability，只视为待清理的历史状态。
 
-## 必读资源
+## 工作流
 
-- 每次执行完整读取 [references/cli-contract.md](references/cli-contract.md)。
-- 每次部署或故障排查完整读取 [references/diagnostics.md](references/diagnostics.md)。
-- 生产、多应用顺序发布或存在 `.numa/pipeline-release.json` 时完整读取 [references/release-policy.md](references/release-policy.md)。
+1. 先读取 [references/release-policy.md](references/release-policy.md)，确认本次请求授权的环境和动作。
+2. 检查源码目录、分支、HEAD、remote、工作树和 `.numa/pipeline-release.json`。生产只发布干净且已推送的提交。
+3. 使用 `numa pipeline inspect APPLICATION --json` 和 `numa pipeline list` 确认 application、tier、canonical Multibranch root、branch child 与参数定义。
+4. 新分支 Job 第一次运行不带业务参数，作为参数初始化；需要强制重建参数时可传 `INIT=true`。初始化成功后必须用新的幂等键触发实际部署。
+5. 实际构建使用 `numa pipeline build`，传明确的 `ENV_ID` 及项目必需参数。生产提供 `--approve-id` 或不少于 10 个字符的 `--production-reason`。
+6. 保存 requestId。结果不明时只用 `pipeline status/log` 或 `pipeline builds` 找回原请求，不换 key 重放。
+7. 完成必须同时核对：平台构建账本/Jenkins 结果、Flux 目标文件与提交、目标集群实际镜像和健康状态。
 
-## 工作边界
-
-- 解释、review、状态查询或诊断保持只读；不触发、停止、重试或修改远程资源。
-- 用户明确要求发布已解析的应用、tier 和 branch 后，可执行对应部署。新增目标、生产影响或 fallback 需要再次授权。
-- 应用/Repository/Job 缺失时转入 `numa-create-application`；项目构建规范缺失且用户要求修复时使用 `mci-build-standards`。
-- 不读取或输出 token cache、Bearer/Cookie、Jenkins/SCM credential、Kubernetes Secret 或数据库密码。
-- v2 writer 结果未知时禁止直接改 Flux、数据库或 Jenkins 结果；本地 Flux 只是在正常流水线不可用且用户明确授权后的独立 fallback，不是账本修复器。
-
-## 1. 建立运行时事实
-
-1. 读取目标仓库的 `AGENTS.md`、部署文档和 `.numa/pipeline-release.json`。
-2. 只用当前运行时帮助确定命令，不凭记忆猜参数：
-
-   ```bash
-   numa --version
-   numa commands --json
-   numa auth status --json
-   numa profile --json
-   numa pipeline --help
-   numa pipeline inspect APPLICATION --json
-   ```
-
-3. 记录 CLI 版本、profile/API origin、当前用户、tier、application、branch 和完整 remote commit。401/403 按身份/权限处理，不绕过服务端。
-4. 判定 delivery mode：存在已验证的 platform-build rollout、server-owned writer 和 `pipeline platform-build` capability 时为 `PLATFORM_V2`；明确的 legacy binding 才为 `LEGACY_V1`。证据不足时停止，禁止猜测或降级。
-
-## 2. 写操作前预检
-
-按顺序核验：
-
-1. **应用目录**：`numa app list --json` 中存在唯一 application；否则分类为 `APPLICATION_NOT_REGISTERED`。
-2. **Jenkins 初始化**：Job、instance、inventory、binding 和目标 branch child 均存在且可构建。完整 multibranch 初始化还要有 INDEX_ONLY/NoTrigger scan 证据；只存在父 Job 或 `scanMode=NONE` 不代表 branch 已就绪。当前服务端在 SCM 分支与 Jenkinsfile 已验证、但 branch child 缺失时，会为同一部署操作自动执行一次安全索引并继续；不得另建影子 Job 或退回默认分支。
-3. **v2 rollout**：`PLATFORM_V2` 必须证明 writer bootstrap、Job provenance、platform-build rollout/configure 为 exact `READY/JENKINS_API_VERIFIED/VERIFIED`，source/Jenkinsfile/build-profile/configuration digest 完整。不得用 legacy manual readiness 代替。
-4. **源码与项目**：工作树干净，HEAD 等于目标远端；Jenkinsfile/build profile 和运行时入口符合该 delivery mode。不要 stash、提交或丢弃用户的无关修改。
-5. **治理**：生产发布需要真实 approval ID 或服务端允许的具体 production reason；不能捏造审批，也不能通过普通参数传入。
-
-## 3. 展示发布计划
-
-触发前展示 CLI/profile/操作者、delivery mode、application 顺序、repository/branch/SHA、Jenkins Job/binding/rollout、preflight、审批、稳定 idempotency key，以及会发生和不会发生的写操作。首次构建、生产发布和 fallback 都是独立授权。
-
-幂等键应稳定标识同一应用、同一源码和同一发布 intent，例如 `APPLICATION-COMMIT_SHA`。同一提交的未知结果复用原 key；真正的新发布才使用新 key。
-
-## 4. 执行与观察
-
-### PLATFORM_V2
-
-按运行时 help 组装命令；v2 不接受任意 Jenkins 参数：
-
-```bash
-numa pipeline platform-build trigger APPLICATION \
-  --tier TIER \
-  --branch BRANCH \
-  --idempotency-key APPLICATION-COMMIT_SHA \
-  --approve-id APPROVAL_ID \
-  --production-reason '具体生产发布原因' \
-  --yes --wait --json
-```
-
-只传策略真实要求的审批字段。Jenkins 负责构建/push 镜像并提交一次 image intent；Flux SCM CAS 由 DevOps server-owned writer 执行，Jenkins 不持有 Flux Git credential。
-
-### LEGACY_V1
-
-只有明确 legacy binding 才使用：
+## 标准命令
 
 ```bash
-numa pipeline build APPLICATION \
-  --tier TIER \
-  --branch BRANCH \
-  --approve-id APPROVAL_ID \
-  --production-reason '具体生产发布原因' \
-  --idempotency-key APPLICATION-COMMIT_SHA \
-  --wait --json
-```
-
-多个应用严格串行；前一个只有平台终态和所需运行态验证均通过后才启动下一个。等待期间至少每分钟给用户一次状态。中断本地观察不会自动停止远端任务。
-
-## 5. 未知结果与安全恢复
+numa pipeline build APPLICATION --tier production --branch BRANCH \
+  --param INIT=true \
+  --production-reason '初始化生产流水线参数' --wait --json
 
-### Trigger/transport 未知
+numa pipeline build APPLICATION --tier production --branch BRANCH \
+  --param ENV_ID=prd \
+  --production-reason '执行生产构建与部署' --wait --json
 
-v2 trigger POST 只发一次：
-
-```bash
-numa pipeline platform-build resolve --client-request-id APPLICATION-COMMIT_SHA --json
-numa pipeline platform-build status REQUEST_ID --watch --json
-numa pipeline platform-build log REQUEST_ID --start 0 --json
+numa pipeline status REQUEST_ID --watch --json
+numa pipeline log REQUEST_ID --offset 0 --json
+numa pipeline builds --app APPLICATION --tier production --branch BRANCH --json
 ```
 
-legacy 通过原请求的 `builds/status/log` 找回。不要因 500/504、连接中断或本地等待取消而换 key 或直接 retry。
-
-### GitOps writer/账本未知
-
-Jenkins 可能在“更新环境镜像”阶段显示失败或 image intent 保持 `UNKNOWN`，但远端 Codeup CAS 和 Flux 部署实际已成功。此时分别核验：
-
-- 原 platform request/build/log；
-- exact application、binding/target、source revision、image repository/tag/digest、expected old head 和稳定 request marker；
-- 远端 target HEAD/revision 与目标 image 字段；
-- Flux GitRepository/Kustomization/HelmRelease/Deployment 的 exact observed revision/image。
-
-远端 marker/HEAD 和健康运行态证明原 CAS 可能已经落地，不授权重放 build、生成新 key、手工重写 Flux、直改数据库或伪造 Jenkins `SUCCESS`。只有 runtime command catalog 明确提供、且服务端能对同一 durable request 做 exact reconciliation 的 reconcile/recover 能力才可推进账本。当前没有该能力时报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED` 并停止。
-
-## 6. 失败分类
-
-只选择有证据的一类，并列出已排除项：
-
-1. `APPLICATION_NOT_REGISTERED`：应用目录缺失。
-2. `JENKINS_NOT_INITIALIZED`：instance/inventory/Job/scan/branch/binding 缺失。
-3. `PLATFORM_V2_NOT_READY`：writer bootstrap、provenance 或 rollout/configure 未达到 exact verified readiness。
-4. `PROJECT_STANDARD`：Jenkinsfile、build profile、产物或启动契约不合规。
-5. `AUTHORIZATION_OR_APPROVAL`：登录、角色或生产审批不足。
-6. `BUILD_OR_RUNTIME_FAILURE`：编译、测试、镜像、迁移、探针或启动失败。
-7. `GITOPS_LEDGER_UNRESOLVED`：远端/运行态可能成功，但 writer response/readback/平台持久化未确认。
-8. `CONTROL_PLANE_OUTAGE`：DevOps API 路由或后端不可用，无法读取正常控制面状态。
-
-日志从第一个根因和最终 `Finished:` 共同判断，不只看最后一层包装异常。
-
-## 7. 运行态与完成标准
-
-v2 完成状态分三列报告：
-
-| 维度 | 必要证据 |
-|---|---|
-| Jenkins/build | 同一 request/build 的明确终态与源码/image identity |
-| Platform ledger | 同一 image intent/CAS 的 verified terminal result |
-| Flux/runtime | exact Git revision、controller healthy、workload exact image 与 readiness |
-
-只有三者一致，且仓库定义的健康/迁移/能力探针通过，才报告平台自动化部署成功。Flux/Deployment 健康但账本未决时只能报告运行态部署成功；“构建已触发”“镜像已推送”或“Flux 已同步”都不能单独冒充完整发布成功。
-
-最终报告先给结论，再列 application、mode、branch/SHA、request/build、幂等键、三维状态、运行态验证、未决风险和安全恢复入口。
-
-## 8. 控制平面自部署与 break-glass
-
-若目标就是提供 Numa pipeline API 的 DevOps 平台且控制面已宕机，停止 CLI 重试并说明自举死锁。只有用户明确授权且已有受控规程时，才用白名单 Jenkins UI/恢复服务固定 branch/commit、审批和审计恢复后端；恢复后立即回到 Numa CLI 校正原请求并验证运行态。手工构建可能不会进入平台账本，必须如实报告。
+首次自然空跑与显式 `INIT=true` 二选一；已经有参数定义时无需重复初始化。详细参数和恢复规则见 [references/cli-contract.md](references/cli-contract.md)，失败分类见 [references/diagnostics.md](references/diagnostics.md)。

package/skills/numa-jenkins-deployment/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Numa Jenkins 发布"
-  short_description: "安全执行 v2 platform-build 与 legacy Jenkins 发布"
-  default_prompt: "使用 $numa-jenkins-deployment 判定目标应用的 PLATFORM_V2 或 LEGACY_V1 delivery mode，完成预检、受治理触发、状态与日志恢复，并分别核验 Jenkins/build、platform image-intent ledger 和 Flux/runtime。结果未知时只恢复原请求，不重放写操作。"
+  short_description: "安全执行 canonical Jenkins/Flux 发布"
+  default_prompt: "使用 $numa-jenkins-deployment 通过 canonical Multibranch pipeline build 完成预检、参数初始化、构建触发、状态与日志恢复，并核验 Jenkins、Flux 和 runtime。结果未知时只恢复原请求，不使用已退役的签名快照表面。"

package/skills/numa-jenkins-deployment/evals/evals.json

@@ -1,69 +1,19 @@
 {
-  "skill_name": "numa-jenkins-deployment",
   "evals": [
     {
-      "id": 1,
-      "prompt": "请制定一个通过 Numa CLI 发布订单系统的执行方案，不要实际触发。order-api 和 order-web 都已确认是 PLATFORM_V2，rollout 为 READY/JENKINS_API_VERIFIED/VERIFIED；仓库 develop 分支 HEAD 与 origin/develop 都是 4f7d9b1，工作树干净；.numa/pipeline-release.json 要求 production，顺序为 order-api 后 order-web，approvalId 为 ORDER-STANDARD-RELEASE，preflight 是 ./scripts/verify-cli-deploy.sh。请给出预检、只读解析、准确构建命令、幂等键、失败恢复和完成条件。",
-      "expected_output": "输出严格串行、可审计且幂等的 Numa CLI生产发布方案，不绕过仓库策略。",
-      "files": [],
-      "expectations": [
-        "先验证 CLI/auth/profile、Git HEAD 与远端、仓库 preflight、应用和 Jenkins binding，再给出写命令",
-        "使用 order-api-4f7d9b1 和 order-web-4f7d9b1 作为每应用稳定幂等键",
-        "生产命令使用 pipeline platform-build trigger、--approve-id ORDER-STANDARD-RELEASE、--yes、--wait 和 --json，且没有任意 --param",
-        "明确 order-api 只有 build、platform ledger、Flux/runtime 三方完成后才允许触发 order-web",
-        "网络或轮询结果不明时按原 key 使用 platform-build resolve/status/log"
-      ]
+      "name": "canonical-v2-production",
+      "prompt": "active-code-inbox 使用 gitopsBuildEntry，生产分支 Job 已初始化。给出发布和未知结果恢复方案。",
+      "expected_output": "使用 pipeline build 传 ENV_ID 和生产原因；保存 requestId，并只用 status/log/builds 恢复；不使用任何签名快照命令。"
     },
     {
-      "id": 2,
-      "prompt": "帮我判断下面三个项目为什么不能用 Jenkins 部署，只诊断不要修改或触发：A 的 numa app list 查不到 application；B 的 application 已存在，但 pipeline inspect 没有 confirmed binding，Jenkins instance inventory 从未同步；C 的 binding confirmed/instance healthy，构建日志显示 Jenkinsfile 没有 buildEntry()、Next.js 容器也没有可运行的 standalone server.js。请分别给出根因分类、证据、责任边界和下一步。",
-      "expected_output": "准确区分应用未登记、Jenkins 未初始化和项目不符合构建/运行规范，并路由到正确专项能力。",
-      "files": [],
-      "expectations": [
-        "A 被分类为 APPLICATION_NOT_REGISTERED，并建议使用 numa-create-application/onboarding，而不是直接建 Jenkins Job",
-        "B 被分类为 JENKINS_NOT_INITIALIZED，指出 inventory、Job/binding 确认责任属于平台初始化",
-        "C 被分类为 PROJECT_STANDARD 或构建运行规范问题，并建议使用 mci-build-standards",
-        "没有触发 build、retry、stop，也没有擅自修改项目",
-        "明确列出已排除类别和每个项目的最小下一步"
-      ]
+      "name": "first-run-initialization",
+      "prompt": "新的 Multibranch 子 Job 尚无 parameterDefinitions，如何完成第一次部署？",
+      "expected_output": "先无业务参数运行或使用 INIT=true 初始化；成功后用新的幂等键和 ENV_ID 触发第二次实际构建。"
     },
     {
-      "id": 3,
-      "prompt": "正在用 numa pipeline 部署 mci-devops-platform 自己。后端构建后，numa pipeline list/builds/log 全部返回 404 或 503，但登录后的 Jenkins 网页仍能看到 build #50 日志，日志末尾是 Spring ApplicationContext 启动失败和 Finished: FAILURE。前端还没部署。请判断原因并给安全恢复方案；不要假设能继续调用已经宕机的 DevOps API。",
-      "expected_output": "识别控制平面自部署死锁，停止 CLI 重试，提出受控 break-glass 后端恢复及恢复后回归 Numa CLI 的顺序。",
-      "files": [],
-      "expectations": [
-        "分类为 CONTROL_PLANE_OUTAGE 与后端运行时失败叠加，而不是 Numa 日志命令缺失",
-        "解释 Jenkins 网页直连而 Numa log 依赖 DevOps 后端代理",
-        "停止重复 build/retry，并明确前端不得在后端恢复前触发",
-        "break-glass 要求白名单 Job、固定 branch/commit、审批、SSO/MFA 或既有受控权限和审计",
-        "后端恢复后切回 Numa CLI校正旧状态、验证运行态，再部署前端，并说明手工构建可能不会回填 request 表"
-      ]
-    },
-    {
-      "id": 4,
-      "prompt": "active-code-inbox 已确认使用 PLATFORM_V2，rollout 为 READY/JENKINS_API_VERIFIED/VERIFIED。请给出生产触发和未知结果恢复命令；不得传任意 Jenkins 参数。",
-      "expected_output": "使用 platform-build trigger，并且未知 trigger 只按原 client request id resolve/status/log，不回退 legacy pipeline build。",
-      "files": [],
-      "expectations": [
-        "触发使用 numa pipeline platform-build trigger，包含稳定 idempotency key、生产审批和 --yes --wait --json",
-        "明确 v2 不接受 --param，也不回退 numa pipeline build",
-        "未知结果使用同一 key 的 platform-build resolve，再按同一 request status/log",
-        "说明 Jenkins 只构建镜像并提交一次 intent，Flux CAS 由 server-owned writer 执行"
-      ]
-    },
-    {
-      "id": 5,
-      "prompt": "某 v2 构建在 Update Environment Image 阶段以 GitOpsUnknownResult 失败，但远端 prd HEAD 含本次 request marker，目标 values 的 image tag/digest 与 intent 一致，Flux 和 Deployment 也已应用且健康；平台 image-intent 仍 UNKNOWN。是否应该重跑构建或本地再推一次 Flux？如何报告状态？",
-      "expected_output": "识别远端 CAS 已落地但平台账本未决，不重放任何写操作；分别报告 runtime 与 ledger，并等待同一 durable request 的服务端 exact reconciliation。",
-      "files": [],
-      "expectations": [
-        "不重跑 build、不换 idempotency key、不创建第二个 image/commit、不手工再写 Flux",
-        "解释 Git CAS 可原子成功，但 response/readback/平台持久化仍可能未知",
-        "要求匹配 application、binding/target、request/build、source、image、expected old head、marker 和 remote HEAD/file content",
-        "报告 RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED，而不是完整平台发布成功",
-        "只有服务端对同一 durable request 的受支持 reconcile/recover 能推进账本；命令不存在时停止而不是发明命令"
-      ]
+      "name": "retired-snapshot-surface",
+      "prompt": "服务端仍显示历史签名快照 capability，是否应继续使用旧触发命令？",
+      "expected_output": "不使用。该表面已退役，只走 canonical pipeline build，并把旧 capability 视为待清理历史状态。"
     }
   ]
 }

package/skills/numa-jenkins-deployment/references/cli-contract.md

@@ -1,120 +1,41 @@
-# Numa Pipeline CLI 调用契约
+# CLI contract
 
-## 1. 固定 CLI、身份与 profile
-
-优先使用 PATH 中的 `numa`，并在一次发布中固定同一入口：
-
-```bash
-numa --version
-numa commands --json
-numa auth status --json
-numa profile --json
-numa pipeline --help
-```
-
-缺少命令时可以只读检查公开最新版，但切换前要告知用户，且发现和写操作必须使用同一已验证版本：
-
-```bash
-npx -y --prefer-online --registry=https://registry.npmjs.org/ \
-  @numa-tech/numa@latest --version
-```
-
-不要硬编码本地源码的 `dist/cli.js` 作为通用方案。401/403 不得通过裸 API、token cache 或手工 Bearer 绕过。
-
-## 2. 判定 delivery mode
+## 只读发现
 
 ```bash
-numa app list --json
+numa pipeline list --app APPLICATION --tier production --branch BRANCH --json
 numa pipeline inspect APPLICATION --json
-numa pipeline list --app APPLICATION --tier TIER --branch BRANCH --json
-numa pipeline platform-build --help
-```
-
-`PLATFORM_V2` 必须同时有运行时 platform-build capability、verified platform-build rollout/server-owned writer、confirmed binding 和可构建 branch。明确 legacy binding 才进入 `LEGACY_V1`。命令存在但服务端 capability/rollout 未就绪不能冒充 v2 ready，也不能静默回退 v1。
-
-Multibranch 父 Job 的 `buildable=false` 可能正常；必须解析目标 branch child。完整初始化需要 INDEX_ONLY/NoTrigger scan 的 task/result 与“没有触发 build”证据，只建父 Job 或 `scanMode=NONE` 不足。
-
-## 3. PLATFORM_V2 构建
-
-运行时帮助：
-
-```bash
-numa pipeline platform-build trigger --help
-numa pipeline platform-build resolve --help
-numa pipeline platform-build status --help
-numa pipeline platform-build log --help
-numa pipeline platform-build stop --help
+numa pipeline builds --app APPLICATION --tier production --branch BRANCH --limit 20 --json
 ```
 
-生产示例：
+必须确认 binding 指向 canonical Multibranch root，目标 branch child 已被 scan 到。不得通过 Job 名猜环境。
 
-```bash
-numa pipeline platform-build trigger APPLICATION \
-  --tier production \
-  --branch BRANCH \
-  --idempotency-key APPLICATION-COMMIT_SHA \
-  --approve-id APPROVAL_ID \
-  --production-reason '具体生产发布原因' \
-  --yes --wait --json
-```
+## 初始化
 
-规则：
+新 branch child 在第一次 Pipeline 执行前没有 parameterDefinitions。第一次运行不带业务参数，`gitopsBuildEntry()` 会写入参数定义并结束。也可以显式传 `INIT=true` 强制重新初始化。
 
-- v2 不接受任意 `--param`；审批只留平台审计，不进入 Jenkins 环境。
-- idempotency key 是稳定 client request id；未知结果复用原 key，新发布才用新 key。
-- Jenkins 只构建/push 镜像并提交一次 image intent；DevOps server-owned writer 执行 Flux SCM CAS。
-- `--wait` 只观察原 request，终端中断不停止远端任务。
+初始化请求与实际部署是两个独立构建，必须使用不同 idempotency key。初始化成功不等于镜像已构建或 Flux 已更新。
 
-## 4. PLATFORM_V2 找回、状态与日志
+## 实际部署
 
 ```bash
-numa pipeline platform-build resolve \
-  --client-request-id APPLICATION-COMMIT_SHA --json
-numa pipeline platform-build list \
-  --app APPLICATION --tier production --json
-numa pipeline platform-build status REQUEST_ID --watch --json
-numa pipeline platform-build log REQUEST_ID --start 0 --json
+numa pipeline build APPLICATION --tier TIER --branch BRANCH \
+  --param ENV_ID=ENVIRONMENT_ID \
+  --production-reason '明确的发布原因' --wait --json
 ```
 
-Trigger POST 只发一次。500/504、连接断开、无效响应或本地等待取消后只用原 key/request GET。不要用第二个 trigger 或新 key探测结果。
-
-Stop 是独立写操作，必须由用户明确要求并遵循生产治理；响应未知后只读取同一 request，不重放 stop。
-
-## 5. GitOps writer 未决契约
-
-若 Jenkins 最终失败发生在 image update/writer 阶段，或 image intent 为 `UNKNOWN`，先保存原 request/build/log。支持的 server reconciliation 必须精确匹配：
-
-- application、service binding/target；
-- client request/idempotency key、request ID、build number；
-- source revision；
-- image repository、tag、digest；
-- expected old target head 和稳定 request marker；
-- remote target HEAD/revision 与目标文件 image 字段。
+按 Jenkinsfile 和平台登记参数补充其它 `--param KEY=VALUE`。不得把 secret、token、password 或 credential 放在参数、日志或聊天中。
 
-Flux GitRepository/Kustomization/HelmRelease/Deployment 只能证明 exact revision/image 的运行态。远端 CAS 和运行时已经成功时，不重放 build、不换 key、不创建第二个 image/commit、不手工写 Flux、不直改数据库或 Jenkins 结果。
-
-只有运行时 command catalog 明确提供的服务端 reconcile/recover，且它恢复同一 durable request，才可推进平台账本。当前 CLI 没有该命令时输出 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED`，等待控制面能力；不要发明命令或使用 local Flux fallback 代替。
-
-## 6. LEGACY_V1 兼容命令
-
-仅用于明确 legacy binding：
+## 恢复
 
 ```bash
-numa pipeline build APPLICATION \
-  --tier production \
-  --branch BRANCH \
-  --approve-id APPROVAL_ID \
-  --production-reason '具体生产发布原因' \
-  --idempotency-key APPLICATION-COMMIT_SHA \
-  --wait --json
-
-numa pipeline builds --app APPLICATION --tier production --branch BRANCH --limit 20 --json
-numa pipeline status REQUEST_OR_BUILD_ID --watch --json
-numa pipeline log REQUEST_OR_BUILD_ID --follow
+numa pipeline status REQUEST_ID --watch --json
+numa pipeline log REQUEST_ID --offset 0 --json
+numa pipeline builds --app APPLICATION --tier TIER --branch BRANCH --json
 ```
 
-Legacy `retry` 创建新请求，只用于已知终态失败后的有意重试，并需要当前有效审批；它不用于未知结果恢复。`stop` 是破坏性操作，必须有用户明确授权。
-
-## 7. 安全输出
-
-最终仅保留 CLI version、profile/API origin、application、delivery mode、tier、branch/SHA、request/build ID、idempotency key、状态、Flux observed revision/image 和脱敏 request ID。不要输出 token、Cookie、Authorization、Jenkins/SCM credential、Secret 或包含密码的参数。
+- 已保存 requestId：只查询同一个 request。
+- 未保存 requestId：按应用、tier、branch 和时间窗口找回。
+- trigger 响应未知：先查账本和 Jenkins，不生成新的请求。
+- Flux 已提交但平台状态未知：核对同一提交和镜像，不重跑构建或再推一次 Flux。
+- 已退役的签名快照命令不得作为恢复手段。

package/skills/numa-jenkins-deployment/references/diagnostics.md

@@ -13,7 +13,7 @@
 | 只有父 Job 或 `scanMode=NONE` | `JENKINS_NOT_INITIALIZED` | 完整的 branch 初始化尚未发生 | 新部署命令会在 SCM/Jenkinsfile 已验证后自动尝试一次 INDEX_ONLY/NoTrigger scan；仍失败时用受治理的初始化/replan 修复 |
 | 目标分支经过自动索引后仍无 child | `JENKINS_BRANCH_FILTERED` | Jenkins 分支策略过滤、索引未收敛或 branch child 不可构建 | 检查 Multibranch branch source/filter 与 Jenkinsfile；不要改用默认分支或影子 Job |
 | Jenkins 索引读取结果不可确认 | `JENKINS_BRANCH_DISCOVERY_FAILED` | Jenkins 上游读取、超时或中断 | 保留同一部署参数和幂等键，先查状态与 Jenkins 索引结果，再按服务端错误恢复 |
-| v2 writer bootstrap/provenance/rollout 非 exact verified readiness | `PLATFORM_V2_NOT_READY` | 新平台构建入口尚未达到安全门禁 | 回到 onboarding/rollout 恢复；不得用 legacy readiness 或 `pipeline build` 降级 |
+| 仍出现签名 snapshot capability | `RETIRED_PIPELINE_SURFACE` | 服务端或本地 CLI 仍暴露已退役路径 | 不调用旧命令；升级组件并只使用 canonical `pipeline build` |
 | 401 | `AUTHORIZATION_OR_APPROVAL` | 登录缺失、过期或 issuer/profile 不匹配 | `auth status`、`profile`，必要时重新登录 |
 | 403 | `AUTHORIZATION_OR_APPROVAL` | 团队权限、平台角色或生产角色不足 | 核对成员关系和 ops-admin；不要索要 token 绕过 |
 | 生产审批缺失/无效 | `AUTHORIZATION_OR_APPROVAL` | 服务端治理拒绝写操作 | 使用真实 approval ID 或合规具体原因 |
@@ -42,7 +42,7 @@ app 存在
 
 使用 `mci-build-standards` 核对：
 
-- Jenkinsfile 使用统一 `buildEntry()`；
+- v2 Jenkinsfile 使用统一 `gitopsBuildEntry()`；尚未迁移的 v1 应用才保留 `buildEntry()`；
 - `APP_NAME` 与应用/镜像名一致；
 - monorepo 的 `APP_HOME` 正确；
 - `TRIGGER_BUILD`、目标 branch 和手动/webhook 策略一致；

package/skills/numa-jenkins-deployment/references/release-policy.md

@@ -1,94 +1,28 @@
-# 仓库驱动的发布策略
+# Release policy
 
-## 策略优先级
+## 授权与目标
 
-按以下顺序解析发布策略：
+部署请求只授权指定应用、环境和正常发布步骤。生产操作前必须通过只读调用解析 exact application、tier、branch、Jenkins binding、GitOps target 和集群。
 
-1. 仓库根目录 `.numa/pipeline-release.json`；
-2. `AGENTS.md` 和仓库部署文档；
-3. 用户为本次发布明确提供的值。
+生产部署只允许干净、已提交且已推送的 revision。不得绕过 dirty-worktree guard，不得发布未跟踪本地状态。
 
-不要擅自覆盖版本化的应用顺序、tier、preflight、approval ID 或生产原因。用户如果要改变发布策略，应把策略修改和实际部署分开 review。
+## 执行顺序
 
-## Manifest v1
+1. 运行项目声明的 preflight/verify。
+2. 确认 canonical Multibranch branch Job 已存在。
+3. 缺少参数定义时先执行初始化构建；初始化不会部署。
+4. 用新的幂等键执行实际构建。
+5. 逐项等待前置应用成功后再启动下游。
+6. 核对 Jenkins、Flux 与 runtime 三方证据。
 
-```json
-{
-  "schemaVersion": 1,
-  "tier": "production",
-  "approval": {
-    "id": "APPROVAL-ID",
-    "reason": "具体生产发布原因"
-  },
-  "preflight": [
-    {
-      "command": "./scripts/verify-cli-deploy.sh",
-      "description": "仓库发布门禁"
-    }
-  ],
-  "applications": [
-    {
-      "code": "backend-application",
-      "description": "先部署迁移和 API"
-    },
-    {
-      "code": "frontend-application",
-      "description": "仅在后端成功后部署"
-    }
-  ]
-}
-```
+## 安全与恢复
 
-校验规则：
+- 不输出 access token、refresh token、Cookie、client secret、Jenkins password、SCM 凭据或 kubeconfig。
+- 不把敏感值放入 Jenkins 参数。
+- 同一请求结果不明时只读恢复，不换 key 重放。
+- 不手工改写 Flux 来掩盖失败。
+- 旧签名快照构建表面已退役；任何仍出现的旧 capability 或数据库记录只作历史审计，不授权调用。
 
-- `schemaVersion` 为 1；
-- tier 只接受 develop、staging、production；
-- applications 至少一个，code 非空且唯一；
-- production 至少提供真实 approval ID 或不少于 10 字符的具体原因；
-- approval ID 匹配 `[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}`；
-- reason 不超过 800 字符；
-- manifest、preflight 和 build parameters 不含 Secret。
+## 完成条件
 
-## Git 与 preflight
-
-生产发布前：
-
-```bash
-git status --short --branch
-git check-ref-format --branch BRANCH
-git fetch origin BRANCH
-git rev-parse HEAD
-git rev-parse origin/BRANCH
-```
-
-要求工作树干净、branch 合法、本地 HEAD 与远端完全一致。不要 stash、reset、checkout 或提交用户的无关修改来强行通过。
-
-逐条检查 preflight 命令内容后按顺序执行；第一条非零即停止。preflight 应覆盖编译、测试、打包和运行时产物契约，而不仅是静态 lint。
-
-## 计划与授权
-
-为每个应用派生稳定幂等键：
-
-```text
-APPLICATION-COMMIT_SHA
-```
-
-展示解析后的应用顺序、tier、branch/SHA、Jenkins binding、preflight、审批和幂等键。用户明确要求按仓库既有 manifest 发布该 branch，且解析没有改变目标或政策时，视为已授权该发布；任何新增目标或生产影响都要重新确认。
-
-每个应用还要记录 delivery mode。`PLATFORM_V2` 使用 `pipeline platform-build trigger`，不接受任意参数；只有明确 `LEGACY_V1` 才使用 `pipeline build`。manifest 不能把 v2 应用静默降级成 legacy，也不能把同一 idempotency key 用于不同 source revision 或 image intent。
-
-## 串行发布
-
-依次执行 manifest applications。v2 前置应用只有 Jenkins/build、platform image-intent ledger 与 Flux/runtime 三方一致并通过健康检查后，才算 `SUCCESS`；后端、数据库迁移或公共 API 等前置应用未满足该条件时，禁止触发前端和下游应用。
-
-如果本地等待中断：
-
-- 远端任务可能仍运行；
-- 复用原幂等键；
-- 先通过 builds/status/log 恢复；
-- 不自动 retry，不推进下一个应用。
-- 若远端 Flux CAS/运行态已经成功但平台 ledger 未决，报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED`，不重复发布，也不推进依赖完整平台成功证明的后续应用。
-
-## 完成验证
-
-除 Jenkins 终态外，还要执行仓库定义的健康、迁移或能力探针。v2 分别报告 Jenkins/build、platform ledger、Flux/runtime，及每个应用的 request/build ID、branch/SHA 和幂等键；失败或 ledger 未决时明确哪些后续应用被跳过。
+只有当平台账本/Jenkins 为成功、Flux 目标文件指向本次镜像、目标工作负载实际运行该镜像且健康时，才报告部署成功。

package/skills/numa-local-flux-deploy/SKILL.md

@@ -16,7 +16,7 @@ Read [local-flux-release.md](references/local-flux-release.md) completely before
 - Never read registry auth files, kubeconfig contents, application secrets, token caches, or `secrets/**`. Check only whether the required authenticated tools can operate.
 - Do not modify Keycloak, database data, unrelated Flux resources, or a live Deployment unless the user separately placed that target in scope.
 - A local interruption or registry/network error creates an unknown result. Inspect the existing image tag, Git ref, Flux revision, and workload before any retry. Reuse the exact operation identity; never create a second release to escape uncertainty.
-- A Numa v2 platform-build whose writer result is `UNKNOWN` is not evidence that the Flux write failed. Before selecting this fallback, inspect the original platform request plus the remote target HEAD/request marker and exact image field. If the intended CAS already landed, do not write Flux again; observe the existing revision and leave platform-ledger reconciliation to the supported server-side recovery path.
+- A retired signed-snapshot build whose writer result is `UNKNOWN` is not evidence that the Flux write failed. Before selecting this fallback, inspect the original request plus the remote target HEAD/request marker and exact image field. If the intended CAS already landed, do not write Flux again; observe the existing revision and leave ledger reconciliation to the supported server-side recovery path.
 
 ## Finish with evidence
 

package/skills/numa-local-flux-deploy/references/local-flux-release.md

@@ -2,7 +2,7 @@
 
 Use this runbook only after the user authorizes the exact deployment and the normal Jenkins/Numa pipeline is unavailable or explicitly excluded. Keep the pipeline failure evidence in the handoff, but do not repeatedly probe or trigger it once the fallback is selected.
 
-Do not select the fallback merely because a v2 platform-build ended with `GitOpsUnknownResult`, a gateway timeout, or an image-intent ledger in `UNKNOWN`. First inspect the original request and the remote Flux branch. If the target HEAD contains the same stable request marker and the resolved image repository/tag/digest matches the original intent, the governed CAS already landed: skip image/Flux writes, observe that exact revision, and report the platform ledger separately. Local fallback cannot reconcile or overwrite the control-plane record.
+Do not select the fallback merely because a retired signed-snapshot build ended with `GitOpsUnknownResult`, a gateway timeout, or an image-intent ledger in `UNKNOWN`. First inspect the original request and the remote Flux branch. If the target HEAD contains the same stable request marker and the resolved image repository/tag/digest matches the original intent, the governed CAS already landed: skip image/Flux writes, observe that exact revision, and report the platform ledger separately. Local fallback cannot reconcile or overwrite the control-plane record.
 
 ## 1. Resolve and freeze the release identity
 

package/dist/integration-bootstrap/client.d.ts

@@ -1,61 +0,0 @@
-import type { AuthConfig } from "../config.js";
-import { type KeycloakTokenProvider } from "../oauth.js";
-import { type IntegrationBootstrapActionKind, type IntegrationBootstrapActionStart, type IntegrationBootstrapActionView, type IntegrationBootstrapApplyStart, type IntegrationBootstrapRunView, type IntegrationBootstrapSession, type IntegrationBootstrapStart, type IntegrationBootstrapTrustAnchorClient } from "./schemas.js";
-export declare const INTEGRATION_BOOTSTRAP_V2_ROOT = "/api/v1/admin/integration-bootstrap/jenkins-gitops-writer/v2";
-export declare const INTEGRATION_BOOTSTRAP_PLAN_SESSION_ROOT = "/api/v1/admin/integration-bootstrap/jenkins-gitops-writer/v2/plan-sessions";
-export declare const INTEGRATION_BOOTSTRAP_RUN_ROOT = "/api/v1/admin/integration-bootstrap/jenkins-gitops-writer/v2/runs";
-export declare const INTEGRATION_BOOTSTRAP_TRUST_ANCHOR_CONFIGURATION = "/public/v1/keycloak-bootstrap/client-configuration";
-export declare const INTEGRATION_BOOTSTRAP_TRUST_ANCHOR_CALLBACK = "/public/v1/keycloak-bootstrap/callback";
-export interface IntegrationBootstrapApplyInput {
-    planSessionNo: string;
-    planDigest: string;
-    clientRequestId: string;
-}
-export interface IntegrationBootstrapActionInput {
-    expectedRunVersion: number;
-    clientRequestId: string;
-}
-export interface IntegrationBootstrapTrustAnchorDocument {
-    realm: "master";
-    clientId: "mci-devops-platform-bootstrap";
-    configurationDigest: string;
-    sourceUrl: string;
-    configuration: IntegrationBootstrapTrustAnchorClient;
-}
-export interface IntegrationBootstrapApi {
-    getTrustAnchorConfiguration(): Promise<IntegrationBootstrapTrustAnchorDocument>;
-    startPlanSession(clientRequestId: string, idempotencyKey: string): Promise<IntegrationBootstrapStart>;
-    resolvePlanSession(clientRequestId: string): Promise<IntegrationBootstrapSession>;
-    getPlanSession(sessionNo: string): Promise<IntegrationBootstrapSession>;
-    startApply(input: IntegrationBootstrapApplyInput, idempotencyKey: string): Promise<IntegrationBootstrapApplyStart>;
-    resolveRun(clientRequestId: string): Promise<IntegrationBootstrapRunView>;
-    getRun(runNo: string): Promise<IntegrationBootstrapRunView>;
-    startAction(runNo: string, kind: Exclude<IntegrationBootstrapActionKind, "APPLY">, input: IntegrationBootstrapActionInput, idempotencyKey: string): Promise<IntegrationBootstrapActionStart>;
-    resolveAction(clientRequestId: string): Promise<IntegrationBootstrapActionView>;
-    getAction(actionNo: string): Promise<IntegrationBootstrapActionView>;
-}
-export interface IntegrationBootstrapClientDependencies {
-    fetch?: typeof fetch;
-    tokenProvider?: KeycloakTokenProvider;
-}
-export declare function integrationBootstrapIdempotencyKey(value: string): string;
-export declare function integrationBootstrapClientRequestId(value: string): string;
-export declare function integrationBootstrapRunNo(value: string): string;
-export declare class IntegrationBootstrapClient implements IntegrationBootstrapApi {
-    private readonly config;
-    private readonly fetchImpl;
-    private readonly tokenProvider;
-    constructor(config: AuthConfig, dependencies?: IntegrationBootstrapClientDependencies);
-    private authenticatedFetch;
-    private json;
-    getTrustAnchorConfiguration(): Promise<IntegrationBootstrapTrustAnchorDocument>;
-    startPlanSession(clientRequestIdValue: string, keyValue: string): Promise<IntegrationBootstrapStart>;
-    resolvePlanSession(clientRequestIdValue: string): Promise<IntegrationBootstrapSession>;
-    getPlanSession(value: string): Promise<IntegrationBootstrapSession>;
-    startApply(input: IntegrationBootstrapApplyInput, keyValue: string): Promise<IntegrationBootstrapApplyStart>;
-    resolveRun(clientRequestIdValue: string): Promise<IntegrationBootstrapRunView>;
-    getRun(value: string): Promise<IntegrationBootstrapRunView>;
-    startAction(runNoValue: string, kind: Exclude<IntegrationBootstrapActionKind, "APPLY">, input: IntegrationBootstrapActionInput, keyValue: string): Promise<IntegrationBootstrapActionStart>;
-    resolveAction(clientRequestIdValue: string): Promise<IntegrationBootstrapActionView>;
-    getAction(value: string): Promise<IntegrationBootstrapActionView>;
-}