@numa-tech/numa 1.14.15 → 1.14.17

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

@@ -0,0 +1,94 @@
+# 仓库驱动的发布策略
+
+## 策略优先级
+
+按以下顺序解析发布策略：
+
+1. 仓库根目录 `.numa/pipeline-release.json`；
+2. `AGENTS.md` 和仓库部署文档；
+3. 用户为本次发布明确提供的值。
+
+不要擅自覆盖版本化的应用顺序、tier、preflight、approval ID 或生产原因。用户如果要改变发布策略，应把策略修改和实际部署分开 review。
+
+## Manifest v1
+
+```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": "仅在后端成功后部署"
+    }
+  ]
+}
+```
+
+校验规则：
+
+- `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 未决时明确哪些后续应用被跳过。

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

@@ -16,9 +16,10 @@ 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.
 
 ## Finish with evidence
 
-Do not call the release successful until GitOps has applied the exact Flux commit, the controller and workload are healthy on the exact image tag, the application readiness check passes, and any optional npm release has passed candidate smoke testing before promotion to `latest`.
+Do not call the release successful until GitOps has applied the exact Flux commit, the controller and workload are healthy on the exact image tag, the application readiness check passes, and any optional npm release has passed candidate smoke testing before promotion to `latest`. When this fallback only verifies a revision already written by a v2 platform request, report `runtime deployed / platform ledger unresolved` until the control plane reconciles the original request.
 
 Report the source commit, image tag and digest, Flux commit/revision, cluster context, controller/workload status, health results, npm version/tags when applicable, and whether Jenkins or Keycloak were touched.

package/skills/numa-local-flux-deploy/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Numa Local Flux Deploy"
   short_description: "Fallback local image builds and Flux releases"
-  default_prompt: "Use $numa-local-flux-deploy to perform a controlled local image and Flux deployment when the normal pipeline is unavailable."
+  default_prompt: "Use $numa-local-flux-deploy only as an explicitly authorized fallback when the normal pipeline is unavailable. First rule out a v2 writer result whose Flux CAS already landed; never rewrite Flux to hide an unresolved platform ledger."

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

@@ -2,6 +2,8 @@
 
 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.
+
 ## 1. Resolve and freeze the release identity
 
 Collect these values from repository and live read-only evidence:
@@ -129,6 +131,7 @@ Use the original identity at every stage:
 | Flux reconciliation | GitRepository/Kustomization revision and conditions | continue observing or request reconciliation for the same commit |
 | workload rollout | controller revision, Deployment generation, Pod image ID | continue observing the same rollout; do not create a new release |
 | health check | workload readiness plus bounded endpoint checks | diagnose the deployed revision; do not infer rollback or success from one timeout |
+| Numa v2 writer ledger | original request plus remote target HEAD/request marker and exact image intent | if the CAS already landed, perform no local write; verify runtime and leave the same durable request `PLATFORM_LEDGER_UNRESOLVED` until server-side reconciliation |
 
 Never hide an unknown result by choosing a new image tag, commit, or audit branch.
 
@@ -169,4 +172,5 @@ Report, without credentials or secret values:
 - controller, Deployment, Pod restart, readiness/liveness, and migration results;
 - npm release commit/tag, package version, and all dist-tags when applicable;
 - any unknown stage still unresolved;
+- when applicable, separate `Jenkins/build`, `platform image-intent ledger`, and `Flux/runtime` status instead of collapsing a healthy runtime into platform success;
 - confirmation that Keycloak and unrelated resources were not modified.