@numa-tech/numa 1.14.15 → 1.14.17

package/skills/numa-create-application/references/numa-cli.md

@@ -173,7 +173,7 @@ CLI 只从 clean Git HEAD 构造受限 bundle，输出不回显文件内容或
       "tier": "DEVELOP",
       "defaultBranch": "main",
       "jenkinsfilePath": "Jenkinsfile",
-      "scanMode": "NONE"
+      "scanMode": "INDEX_ONLY"
     },
     "targetKey": "develop",
     "profileCode": "MCI_FLUX_V1",
@@ -231,7 +231,7 @@ numa app inspect <session-no> --watch --after-sequence <last-sequence> --json
 session/run/key。retry 后仍须读取同一 `GITOPS_V2_WRITER_BOOTSTRAP` 的 exact 成功证据；UNKNOWN/drift
 继续阻断，不重放 first-build POST、不手工修改 SCM、不创建新身份。
 
-Jenkins Job Control Plane 使用 `numa jenkins job plan .../apply/status/events`；默认 `scanMode=NONE`，`INDEX_ONLY` 也必须由服务端 NoTrigger 验证。`app jenkins-binding confirm` 只确认关系，不触发 build。首次 build 必须单独执行 `app first-build decide --decision trigger`；生产场景切换到 `numa-jenkins-deployment` 并提供真实审批证据。
+Jenkins Job Control Plane 使用 `numa jenkins job plan .../apply/status/events`；独立 Job 操作仍可使用 `scanMode=NONE`，但完整应用初始化固定使用服务端 NoTrigger 验证的 `INDEX_ONLY` 并要求目标 branch child 可构建。`app jenkins-binding confirm` 只确认关系，不触发 build。首次 build 必须单独执行 `app first-build decide --decision trigger`；生产场景切换到 `numa-jenkins-deployment` 并提供真实审批证据。
 
 新应用 v2 与 legacy writer 是两条并行路径。v2 使用同一 Application/session/repository/binding/target 做 Job provenance replan，完成 GitOps structural apply 后再由 onboarding 自动执行上述 internal bootstrap；不运行 legacy migration。旧 v1 应用确有 pointer 缺失时才运行 migration。`code-index` 的旧 approved commit `230e0f...` 只属于 v1，v2 必须使用本次新发布的 shared-library 40hex：
 
@@ -264,6 +264,9 @@ v2 `platform-build-rollout` 所有写入要求 Idempotency-Key 与 `--yes`，且
   numa jenkins job status --client-request-id <original-id> --json
   numa app publication resolve <session-no> --client-request-id <original-id> --json
   numa app inspect <session-no> --after-sequence <last-sequence> --json
+  numa pipeline platform-build resolve --client-request-id <original-id> --json
+  numa pipeline platform-build status <request-id> --watch --json
+  numa pipeline platform-build log <request-id> --start 0 --json
   ```
 
   CLI 只有在写前 event cursor 之后观察到与本次 planHash/精确 intent 匹配的新持久事件时，才可能返回 `recovered_from_status=true`；既有 `WAITING_EXTERNAL` 或旧输出字段不能作为恢复证据。Repository、Publication、Jenkins 的 resolved run 还必须匹配请求 planNo 和响应中可用的稳定 workload identity。
@@ -271,6 +274,7 @@ v2 `platform-build-rollout` 所有写入要求 Idempotency-Key 与 `--yes`，且
 - HTTP 2xx 后客户端 schema 解析失败不代表服务端失败。先 list/get 核实资源，禁止直接重放 POST。
 - legacy migration plan 无 Idempotency-Key/resolve-by-key，结果未知时 fail closed。Rollout plan create 也不按 key resolve；apply 必须用写前 list baseline 与写后 exact application/instance/plan mode/new version 恢复；configure 未知时不重放，只 GET 同 rollout，并要求 exact identity/intent、new version、credential booleans=true、observed shared-library revision、verified source revision、Jenkinsfile/configuration digest 与 `READY/JENKINS_API_VERIFIED/VERIFIED`，否则 result unknown；source revision 不与 approved library revision 混同。旧 readiness 必须用同 rollout 的 exact reference/mode/status/identity/new version 恢复。预存 READY/LEGACY 不是成功证据。
 - `WAITING_EXTERNAL` 使用 `resume`；可重入失败使用 `retry`；HEAD 移动使用 `reassess`。按服务端 recovery action 选择，不自行跳步骤。对 v3 writer bootstrap，按 recoveryAction 显式执行 `writer-bootstrap ensure`；初始响应未知只重放原 key，已持久 child UNKNOWN 才用 `app retry <same-session>` 恢复 same-run/key，普通 status/inspect 和 first-build unknown recovery 都保持纯读。
+- v2 platform-build 的 trigger/stop POST 都只发送一次。若 Jenkins 在 GitOps image update 阶段失败或 image intent 为 `UNKNOWN`，只用原 request 的 resolve/status/log；再由平台核验 exact application、binding/target、source revision、image repository/tag/digest、expected old head、request marker、远端 target HEAD/revision/file content。Flux/Deployment 已消费 exact revision 只证明运行态，不证明平台账本完成。command catalog 未提供同一 durable request 的 reconcile/recover 时，报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED` 并停止；不要换 key、重放 build、手工写 Flux、直改数据库或伪造成功。
 - 生产 `pipeline build`、stop、retry 需要独立审批 ID 或具体 production reason；本 skill 默认只创建/核验流水线。
 - 不启动或遗留 `kubectl port-forward`、SSH tunnel 或后台代理来绕过网关；只读恢复仍失败时报告 profile/API origin、request ID 和上述恢复命令，等待平台恢复。
 

package/skills/numa-create-application/references/promote-workflows.md

@@ -93,7 +93,7 @@ COMPLETED
 
 已部署应用可采用 `ATTACH_APPLICATION`，但必须验证团队、repository、Jenkins 与运行态身份一致。Candidate adopt 不得创建一个与 onboarding reservation 冲突的第二个 Application。
 
-Jenkins Job 创建、配置和 `INDEX_ONLY` scan 必须验证不会触发 build；默认 `scanMode=NONE`。首次 build 是独立 promote 决策：`DEFER` 永不触发且 parent 保持 `WAITING_EXTERNAL`，`TRIGGER` 必须使用 confirmed binding。生产 build 转入 `numa-jenkins-deployment`，要求真实审批依据。
+Jenkins Job 创建、配置和 `INDEX_ONLY` scan 必须验证不会触发 build；完整应用初始化固定使用 `scanMode=INDEX_ONLY`。首次 build 是独立 promote 决策：`DEFER` 永不触发且 parent 保持 `WAITING_EXTERNAL`，`TRIGGER` 必须使用 confirmed binding。生产 build 转入 `numa-jenkins-deployment`，要求真实审批依据。
 
 ### 并行 v2 writer 与 Jenkins rollout gate
 
@@ -137,6 +137,30 @@ image intent，不持有 Flux Git credential，不运行 kubectl。DevOps server
 执行 SCM CAS；未知结果只按原 request id GET，Observer 独立证明 Flux 运行态。旧 `pipeline build` 与
 legacy writer 行为不变。
 
+### Platform-build writer 结果对账
+
+`platform-build` 可能出现一种特殊分裂状态：Jenkins 最终显示失败或 image intent 保持 `UNKNOWN`，但
+Codeup/Flux 远端 CAS 实际已把目标分支推进到本次提交，Flux 也可能已经部署该镜像。此时 Git push/CAS
+的原子性并未失效；不确定的是响应、readback 或平台本地结果持久化是否完成。
+
+按下面顺序处理：
+
+1. 保存原 request id、client request/idempotency key、build number 和完整日志；只运行
+   `pipeline platform-build resolve/status/log` 等原请求只读命令。
+2. 由受支持的平台只读接口核验固定元组：application、service binding/target、source revision、image
+   repository/tag/digest、expected old head、稳定 request marker、远端 target HEAD/revision 和目标 image
+   字段。任何一项不一致都不能恢复为成功。
+3. 单独读取 Flux GitRepository/Kustomization/HelmRelease/Deployment evidence。它只证明运行态是否消费了
+   exact revision/image，不改变 Jenkins 或平台账本终态。
+4. 如果运行时健康而账本仍未决，报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED`。禁止重新触发
+   build、换 key、生成第二个 image/commit、手工重复写 Flux、直改数据库或伪造 Jenkins `SUCCESS`。
+5. 只有 runtime command catalog 明确提供、且服务端能以同一 durable request 做 exact reconciliation
+   的 reconcile/recover 能力，才允许把账本推进到 verified terminal state。当前 CLI 没有该命令时停止在
+   未决状态并交给控制面修复；不要用 local Flux fallback 代替账本恢复。
+
+因此完成状态必须分开报告：`Jenkins/build`、`platform image-intent ledger`、`Flux/runtime`。三者一致才是
+平台自动化闭环完成；只有后者健康时只能说运行态已部署。
+
 若 migration plan 返回 `GITOPS_RAW_SECRET_FORBIDDEN`，这是 hard blocker，不是“按 recovery 处理”的泛化提示：
 
 1. 不读取、复制或回显 Secret value，不把 raw value 改成普通 base64，不直接删除 Secret，也不绕过 migration/GitOps plan 手改目标。
@@ -157,6 +181,7 @@ legacy writer 行为不变。
 - 普通 profile HTTPS 网关失败时，Repository/Jenkins run 按原 clientRequestId 查 `status`；standalone publication plan create 的 500/504、连接中断或无效 2xx 只按原 key 有界 GET `publication plan resolve`，校验 `STANDALONE`/repository identity，POST 只发一次，retryable 404 只稍后 GET。普通 session action 先 `app inspect`；publication attach 必须先按原 `sessionNo/clientRequestId` 执行 `app publication resolve`。其 retryable 404 只能稍后重查，禁止自动重放 attach；不要启动或遗留 port-forward/tunnel 旁路。
 - session action 的自动恢复必须以写前 event cursor 为基线，只接受 cursor 之后与本次 planHash/精确 intent 匹配的新持久事件；既有 `WAITING_EXTERNAL` 或旧 observer/build/binding 字段不是本次写成功的证据。child run resolve 必须至少匹配请求 planNo，并校验响应中可用的 repository/workload identity。
 - v3 bootstrap 是独立受认证 action；CLI 只提交原 session/Idempotency-Key，服务端锁定全部拓扑与固定三文件。PENDING 只读等待；初始 POST 未知只以原 key 精确重放，已持久 child UNKNOWN 才通过显式通用 `app retry <same-session>` 恢复原 run/key。普通 status/inspect 和 first-build recovery 都是纯读；不得重放 first-build POST、调用 legacy migration、手工写 SCM 或另建身份。retry 后仍 UNKNOWN 或 drift 时保持 fail closed。
+- platform-build writer UNKNOWN 只按原 request 对账；远端 marker/HEAD 和 Flux healthy 是“原 CAS 可能已落地”的证据，不是重放授权，也不能单独把平台账本或 Jenkins 终态改成成功。缺少服务端 reconcile/recover capability 时明确保持 `PLATFORM_LEDGER_UNRESOLVED`。
 - Jenkins scan 不等于 build；观察到意外 build 时停止父流程并报告。
 - GitOps target 只有 topology validation 时保持 DRAFT；Jenkins attestation 最多推进 VERIFYING，只有独立 Flux Observer evidence 能推进 ACTIVE。
 
@@ -171,3 +196,4 @@ legacy writer 行为不变。
 - Jenkins GitOps rollout automatic configure 达到 `READY/JENKINS_API_VERIFIED/VERIFIED`，observed shared-library revision、verified source revision、Jenkinsfile/configuration digest 均完整且与各自 intent 一致；source revision 不要求等于 approved library revision。仅旧部署可记录 manual compatibility evidence。
 - GitOps service binding 和 exact Observer scope 存在；configRevision 与 observedRevision 一致后才 ACTIVE。
 - 未经独立生产授权不得触发 build；触发后必须以 Jenkins 终态和 Flux/Observer evidence 验收。
+- platform-build 还必须核验平台 image-intent ledger；Jenkins/build、ledger 与 Flux/runtime 未三方一致时，不得把运行态部署成功描述为完整平台发布成功。

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

@@ -0,0 +1,147 @@
+---
+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 已落地但平台账本未决，以及控制面故障。
+---
+
+# Numa Jenkins Deployment
+
+把 Numa CLI 当作 Jenkins 和平台 GitOps writer 的唯一受控入口。先判定 delivery mode，再证明应用、源码、Job、binding、rollout、审批与运行态指向同一发布；不要用重复触发掩盖初始化或结果对账问题。
+
+## 必读资源
+
+- 每次执行完整读取 [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)。
+
+## 工作边界
+
+- 解释、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. 未知结果与安全恢复
+
+### Trigger/transport 未知
+
+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
+```
+
+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 校正原请求并验证运行态。手工构建可能不会进入平台账本，必须如实报告。

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

@@ -0,0 +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。结果未知时只恢复原请求，不重放写操作。"

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

@@ -0,0 +1,69 @@
+{
+  "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"
+      ]
+    },
+    {
+      "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，也没有擅自修改项目",
+        "明确列出已排除类别和每个项目的最小下一步"
+      ]
+    },
+    {
+      "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 能推进账本；命令不存在时停止而不是发明命令"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,120 @@
+# Numa Pipeline CLI 调用契约
+
+## 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 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
+```
+
+生产示例：
+
+```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
+```
+
+规则：
+
+- v2 不接受任意 `--param`；审批只留平台审计，不进入 Jenkins 环境。
+- idempotency key 是稳定 client request id；未知结果复用原 key，新发布才用新 key。
+- Jenkins 只构建/push 镜像并提交一次 image intent；DevOps server-owned writer 执行 Flux SCM CAS。
+- `--wait` 只观察原 request，终端中断不停止远端任务。
+
+## 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
+```
+
+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 字段。
+
+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
+```
+
+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 或包含密码的参数。

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

@@ -0,0 +1,121 @@
+# Jenkins 部署诊断树
+
+## 快速判定
+
+| 观察结果 | 分类 | 含义 | 下一步 |
+|---|---|---|---|
+| `numa app list` 没有 application | `APPLICATION_NOT_REGISTERED` | 应用尚未进入 DevOps 应用目录 | 使用 `numa-create-application` 做 onboarding plan；不要直接创建 Jenkins Job |
+| 应用存在，但 pipeline list/inspect 无 binding | `JENKINS_NOT_INITIALIZED` | delivery/Jenkins 绑定尚未创建或确认 | 平台管理员完成 Jenkins inventory、Job 候选和 binding |
+| binding 非 `CONFIRMED` | `JENKINS_NOT_INITIALIZED` | 平台尚未确认应用与 Job 的治理关系 | 确认 binding，不要绕过平台直触发 |
+| instance unhealthy 或 stale | `JENKINS_NOT_INITIALIZED` | Jenkins 凭据、网络或 inventory sync 不可用 | 测试 instance 并同步 inventory |
+| Multibranch 父 Job `buildable=false` | 继续检查 branch | 父容器常常不可直接构建 | 用目标 branch 解析直接子 Job；不要仅凭父字段阻断 |
+| branch 子 Job 不存在/不可构建 | `JENKINS_NOT_INITIALIZED` 或 SCM 分支问题 | Jenkins 尚未索引该分支，或分支不符合 Job 规则 | 确认远端 branch、multibranch scan 和子 Job |
+| 只有父 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` 降级 |
+| 401 | `AUTHORIZATION_OR_APPROVAL` | 登录缺失、过期或 issuer/profile 不匹配 | `auth status`、`profile`，必要时重新登录 |
+| 403 | `AUTHORIZATION_OR_APPROVAL` | 团队权限、平台角色或生产角色不足 | 核对成员关系和 ops-admin；不要索要 token 绕过 |
+| 生产审批缺失/无效 | `AUTHORIZATION_OR_APPROVAL` | 服务端治理拒绝写操作 | 使用真实 approval ID 或合规具体原因 |
+| Jenkinsfile/buildEntry/APP_NAME/入口不合规 | `PROJECT_STANDARD` | 项目不符合 MCI 构建/运行契约 | 使用 `mci-build-standards` 检查并按用户授权修复 |
+| 编译、测试、镜像阶段失败 | `BUILD_OR_RUNTIME_FAILURE` | 源码或依赖问题 | 定位首个失败命令，修复后重跑 preflight |
+| Pod 启动、探针或 ApplicationContext 失败 | `BUILD_OR_RUNTIME_FAILURE` | 镜像已构建但运行态失败 | 从首个 root cause 修复；增加启动/Bean wiring 契约测试 |
+| Jenkins image update 失败/intent `UNKNOWN`，远端 marker/HEAD 已匹配 | `GITOPS_LEDGER_UNRESOLVED` | CAS 可能已落地，但 writer response/readback/本地账本未确认 | 不重放；核验 exact intent 与 Flux observed revision，等待同一 durable request 的服务端 reconcile/recover |
+| build/status/log 同时 404/500/503 | `CONTROL_PLANE_OUTAGE` | DevOps API 或其网关路由不可用 | 停止 CLI 重试；若是自部署，进入受控 break-glass |
+
+## 应用未登记与 Jenkins 未初始化的区别
+
+先查应用目录，再查流水线：
+
+```text
+app 不存在
+└─ 需要应用 onboarding：团队、SCM、环境、技术栈、delivery
+
+app 存在
+└─ pipeline/binding 不存在
+   └─ 需要 Jenkins 初始化：instance、inventory、Job/branch、confirmed binding
+```
+
+不要因为两者最终都表现为“不能部署”就混为一谈。应用 onboarding 可能创建/绑定流水线，但需要独立确认和服务端 plan；部署 Skill 不直接替代该流程。
+
+## 项目规范诊断
+
+使用 `mci-build-standards` 核对：
+
+- Jenkinsfile 使用统一 `buildEntry()`；
+- `APP_NAME` 与应用/镜像名一致；
+- monorepo 的 `APP_HOME` 正确；
+- `TRIGGER_BUILD`、目标 branch 和手动/webhook 策略一致；
+- Java/Go 使用合适节点，Node/Python 使用可访问依赖源的节点；
+- Java 产物是 Spring Boot layered jar；
+- Next.js standalone 有可运行的 `server.js` 和正确 COPY_PATH；
+- Python 有明确 entrypoint；
+- 应用监听 `PORT=8080`，启动命令、readiness/liveness 可用；
+- 不用普通构建参数传 credential、token、password、secret。
+
+构建成功不代表部署成功。日志出现 Pod startup、ApplicationContext、probe timeout 或容器入口错误时，应继续按运行时规范排查。
+
+## 日志分析顺序
+
+1. 保存 request ID、build number、branch 和 commit。
+2. 从日志末尾确认 Jenkins `Finished:`。
+3. 向前寻找第一个 `Caused by`、失败命令、测试失败或 probe/startup 错误。
+4. 区分流水线包装错误与应用 root cause。
+5. 报告最小修复面；未经用户授权不要顺手修改项目。
+
+常见状态陷阱：
+
+- `UNKNOWN` 不等于失败，也不等于成功。
+- `UNKNOWN` 同时带 `completedAt`，而 Jenkins 日志结尾是 `Finished: FAILURE`，通常是状态归一或旧服务版本问题；按失败处理并报告映射缺口。
+- `--wait` 没有输出可能只是只在终态输出 JSON；用只读 `builds` 交叉检查，不要重复触发。
+- HTTP 500/503 发生在被部署后端滚动时，远端 Jenkins 可能继续运行；服务恢复后用原请求续查。
+- Jenkins `Finished: FAILURE` 若根因是 `GitOpsUnknownResult`，不能直接归类为源码构建失败。远端 target HEAD 含本次稳定 request marker、image repository/tag/digest 与原 intent 精确匹配且 Flux 已应用时，分别报告 Jenkins/build、platform ledger、Flux/runtime；runtime healthy 仍不等于账本成功。
+- Git ref 的 CAS/fast-forward 更新可以是原子的，但 API 响应、后续 readback 或平台持久化仍可能失败；这就是“远端成功、平台未知”的窗口，不是 Git push 半成功。
+
+## GitOps ledger 对账清单
+
+按同一原请求核验，不从日志文本或邮箱/显示名推断 identity：
+
+1. application、binding/target、request ID、client request key 和 build number；
+2. source revision 与 image repository/tag/digest；
+3. expected old head、稳定 request marker、remote target HEAD/revision 和目标 image 字段；
+4. Flux GitRepository/Kustomization/HelmRelease observed revision；
+5. Deployment/Pod exact image 与 readiness。
+
+全部匹配可报告 `RUNTIME_DEPLOYED / PLATFORM_LEDGER_UNRESOLVED`，但不能伪造平台成功。任何冲突都是 fail closed。当前 command catalog 没有同一 durable request 的服务端 reconcile/recover 时，停止写操作并把修复责任交给控制面。
+
+## 自部署故障与 break-glass
+
+典型证据：
+
+- 目标应用就是 `mci-devops-platform` 或提供 Numa pipeline API 的服务；
+- Jenkins 页面可见日志，但 `numa pipeline log` 返回 404/503；
+- `pipeline list`、`builds` 和其他新 API 同时不可用；
+- 网页是直连 Jenkins，而 CLI 通过 DevOps 后端代理。
+
+处理：
+
+1. 明确当前 CLI 控制面已经丢失，不再尝试 `build/retry`。
+2. 通过已有、审计化的 Jenkins SSO 或独立恢复服务查看日志。
+3. 修复并推送代码，完成本地/CI preflight。
+4. 经用户明确授权，手工触发白名单后端 Job，固定 branch/commit 和 approval ID。
+5. 后端恢复后用 Numa CLI验证新能力、刷新旧请求终态，再部署前端或其他依赖应用。
+6. 记录手工构建可能未进入平台 request 表；不要伪造 request ID。
+
+break-glass 不是匿名接口、共享管理员密码或绕过审批。理想实现独立于被管理平台，权限最小、目标白名单、MFA、强制审批、全量审计，并在恢复后回填记录。
+
+## 排除报告模板
+
+```markdown
+结论：<分类与是否可继续部署>
+
+证据：
+- 应用登记：<存在/缺失>
+- Jenkins 初始化：<instance/job/branch/binding>
+- 项目规范：<preflight/关键缺口>
+- 身份治理：<profile/role/approval>
+- 构建运行态：<request/build/Finished/root cause>
+
+已排除：<其他类别及证据>
+下一步：<责任方、最小动作、恢复后验证>
+```