@numa-tech/numa 1.14.28 → 1.14.30

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

@@ -1,281 +1,51 @@
-# Numa CLI 执行契约
+# Numa CLI reference
 
-## 目录
-
-- [命令解析](#命令解析)
-- [只读发现](#只读发现)
-- [安全输出](#安全输出)
-- [入驻执行](#入驻执行)
-- [恢复规则](#恢复规则)
-
-## 命令解析
-
-优先使用 PATH 中的 `numa`。缺失时建议用户安装 launcher，或用以下临时入口执行公开诊断：
+## 发现
 
 ```bash
-npx -y --prefer-online --registry=https://registry.npmjs.org/ @numa-tech/numa@latest --version
-```
-
-不要硬编码本地 Numa 源码路径。先执行 `numa commands --json`，以运行时命令目录为准；CLI 增加一等 cluster/database 命令后优先使用新命令。
-
-## 只读发现
-
-按需执行：
-
-```bash
-numa --version
-numa auth status --json
-numa config --show --json
-numa profile --json
-numa commands --json
 numa app capabilities --json
-numa app options team --json
-numa app options system --json
-numa app options business-domain --json
-numa app options environment --json
-numa repository connection list --json
-numa repository capabilities --connection <code> --consumer application-onboarding --json
-numa app scm inspect <code> --json
-numa repository namespace list --connection <code> --json
-numa repository remote list --connection <code> --search <name> --json
-numa app list --json
-numa pipeline list --app <application-code> --json
+numa app options --json
+numa pipeline list --app APPLICATION --json
+numa pipeline inspect APPLICATION --json
 ```
 
-兼容期仍可只读使用 `numa app scm`，但仓库生命周期必须使用顶层 Repository Control Plane：
-
-```bash
-numa repository remote list --connection <connection-code> --search <repository-name> --json
-```
+## Repository 与 Publication
 
-`repository capabilities --consumer` 同时接受可复制的 `application-onboarding` 和规范
-`APPLICATION_ONBOARDING`（下划线形式也保留），发送给服务端时统一为规范枚举。普通
-`app scm inspect/list`、`repository connection list` 以及 capabilities 的 nested connection 都只读取
-安全布尔字段 `codeupCredentialReadinessAvailable`、`codeupAccessTokenConfigured`、
-`codeupCloneCredentialConfigured`，不读取 credential。只有 availability=`true` 时才解释 configured：
-显式 `false` 是 missing；availability=`false`/缺失或 configured 缺失均是 unknown 并 fail closed。
-`capabilities.executableMode` 不是 clone credential 证据。
+始终复用同一 onboarding session、planHash、clientRequestId 和 idempotency key。具体子命令以运行时 `numa commands --json` 与 `--help` 为准；命令缺失时标记 capability unavailable，不用通用 request 绕过。
 
-平台管理员交互轮换 Codeup OpenAPI AT 与 HTTPS clone 凭据时使用原生隐藏提示，不把值写入 argv、环境变量、聊天或临时 JSON：
+## Jenkins Job
 
 ```bash
-numa app scm rotate <connection-code> --revision <version> --credential-prompt --yes --json
+numa jenkins job plan ... --scan-mode INDEX_ONLY --json
+numa jenkins job apply ... --yes --json
+numa jenkins job status --client-request-id ORIGINAL_ID --json
 ```
 
-AT 与 clone password 隐藏输入，clone password 需二次确认；clone username 可见。提示只写 stderr，JSON 结果仍只写 stdout。GitHub App 私钥是多行材料，不允许交互粘贴，继续使用 chmod 600 文件或重定向 stdin。自动化也使用受保护文件/stdin，不用脚本拼接明文 JSON。
-
-团队选项可见不等于当前用户具有 `MEMBER+`。通过运行时 command catalog 找团队成员查询能力；缺失时用批准的只读平台 API，并把无法证明的成员资格标记为 `UNRESOLVED`。
+确认 branch child 被索引且没有 build 被触发，再确认 application binding。
 
-## 安全输出
-
-`numa request --json` 可能包含响应 headers。永远在命令输出到工具日志前做字段 allowlist；不要输出 `.response.headers`：
+## 初始化与部署
 
 ```bash
-set -o pipefail
-numa request /approved/read-only/path --json |
-  jq 'if .ok then {ok, status: .response.status, body: .response.body} else {ok, error} end'
-```
-
-对 body 继续裁剪到本次决策需要的字段。禁止显示 token cache、`set-cookie`、Authorization、credential、password、secret、private key、完整 connection string。
-
-`app publication attach --json` 的安全契约只包含 session/plan 标识、state、tree/manifest 计数、
-digest、幂等键和恢复证据；不得输出完整 session draft/plan、manifest path、`sourceRoot`、
-`contentBase64` 或 provider payload。
+numa pipeline build APPLICATION --tier TIER --branch BRANCH \
+  --param INIT=true --production-reason '初始化流水线参数' --wait --json
 
-attach 的 POST 返回 500/504、连接中断或 2xx body 无法解析时，CLI 必须用原值有界轮询精确只读
-resolve endpoint；手工恢复命令为：
-
-```bash
-numa app publication resolve <session-no> --client-request-id <original-id> --json
+numa pipeline build APPLICATION --tier TIER --branch BRANCH \
+  --param ENV_ID=ENVIRONMENT_ID --production-reason '执行应用部署' --wait --json
 ```
 
-该命令不上传 bundle、不重放 attach。200 必须是同一 session 的 `APPLICATION_ONBOARDING` binding
-且 `replayed=true`；retryable 404 `ONBOARDING_PUBLICATION_PLAN_NOT_RESOLVED` 表示可稍后重查，不能
-改用新 key 或新 session。
+新 branch child 也可第一次无业务参数自然初始化。初始化与部署必须使用不同幂等请求。
 
-## Repository Control Plane
+已退役的签名快照命令不得调用。
 
-缺少远端仓库且计划由 Application Onboarding 消费时，先幂等创建空 session，再发现 namespace/capability 和创建不可变计划：
+## 恢复
 
 ```bash
-numa app begin --mode new \
-  --idempotency-key begin-order-service --yes --json
-numa repository capabilities \
-  --connection codeup-main --consumer application-onboarding --json
-numa repository namespace list \
-  --connection codeup-main --search 'numa/framework' --json
-numa repository remote list \
-  --connection codeup-main --search order-service --json
-numa repository plan create \
-  --connection codeup-main --namespace 123 --name order-service \
-  --visibility private --initialization readme \
-  --consumer application-onboarding --consumer-ref <begin返回的session-no> \
-  --owner-team-id 12 --json
-numa repository plan get <plan-no> --json
-numa repository create \
-  --plan-no <plan-no> --plan-hash <64-hex> \
-  --client-request-id <stable-key> --idempotency-key <same-key> \
-  --yes --json
+numa app inspect SESSION --watch --json
+numa repository status --client-request-id ORIGINAL_ID --json
+numa publication status --client-request-id ORIGINAL_ID --json
+numa jenkins job status --client-request-id ORIGINAL_ID --json
+numa pipeline status REQUEST_ID --watch --json
+numa pipeline log REQUEST_ID --offset 0 --json
 ```
 
-Repository `create` 只负责远端生命周期和 catalog 一致性，不会隐式读取或推送本地目录。Codeup 的本地历史发布使用 `README` 初始化，随后由 Publication CAS 精确替换 tree；不要创建空仓后直接 Git push。
-
-独立仓库发布可使用顶层 `publication scan/plan/apply/status/events`。Application Onboarding 不得把这种 `STANDALONE/JWT` plan 冒充 child；必须在 parent 等待 `ATTACH_PUBLICATION_PLAN` 后调用：
-
-```bash
-numa app publication attach <session-no> \
-  --source <clean-git-root> \
-  --commit-message 'feat: publish existing project' \
-  --client-request-id <stable-child-key> \
-  --idempotency-key <same-key> --yes --json
-```
-
-CLI 只从 clean Git HEAD 构造受限 bundle，输出不回显文件内容或本地绝对路径。命令不存在时按 promote workflow 标记 `MANUAL_BRIDGE`，不能把普通 Git 推送写成平台功能。
-
-## 入驻执行
-
-普通接入可使用 schemaVersion 2；创建并 promote 已有本地项目必须使用 schemaVersion 3，把 Publication、Jenkins Job、GitOps、Observer 和首次 build 拆成独立 gate：
-
-```json
-{
-  "schemaVersion": 3,
-  "mode": "NEW",
-  "catalogStrategy": "CREATE_NEW",
-  "application": {
-    "code": "order-service",
-    "name": "Order Service",
-    "teamId": 12,
-    "systemId": 7,
-    "defaultEnvironmentId": 2
-  },
-  "repositoryStrategy": "CREATE_NEW",
-  "repositoryPlanRef": {
-    "planNo": "rplan_...",
-    "planHash": "64-lowercase-hex"
-  },
-  "projectStrategy": "PUBLISH_PROJECT",
-  "technology": {
-    "stackCode": "java-mci",
-    "templateCode": "java-mci-standalone",
-    "repoMode": "STANDALONE",
-    "parameters": {}
-  },
-  "delivery": {
-    "jenkinsRequired": true,
-    "gitopsRequired": true,
-    "nacosRequired": false,
-    "tiers": ["DEVELOP"],
-    "jenkins": {
-      "operation": "CREATE_MULTIBRANCH",
-      "instanceCode": "numa",
-      "parentFullName": "mci/develop",
-      "jobName": "order-service",
-      "tier": "DEVELOP",
-      "defaultBranch": "main",
-      "jenkinsfilePath": "Jenkinsfile",
-      "scanMode": "INDEX_ONLY"
-    },
-    "targetKey": "develop",
-    "profileCode": "MCI_FLUX_V1",
-    "profileVersion": "1",
-    "structuralSpec": { "workloadKind": "SPRING", "service": { "port": 8080 } },
-    "observerScopeIntent": {
-      "kustomizationNamespace": "flux-system",
-      "kustomizationName": "develop",
-      "helmReleaseNamespace": "develop",
-      "helmReleaseName": "order-service",
-      "workloadNamespace": "develop",
-      "workloadKind": "Deployment",
-      "workloadName": "order-service"
-    }
-  }
-}
-```
-
-`CREATE_NEW` 使用 `repositoryPlanRef {planNo,planHash}`；`ATTACH_EXISTING` 使用 `repositoryRef {repositoryKey,expectedHead}`。已有本地源码但无 remote 时，先锁 Repository plan，再创建 v3 parent；不要用受管模板覆盖本地项目，也不要另建第二个 `ATTACH_EXISTING` session。
-
-`PUBLISH_PROJECT` 必须接续 `app begin` 创建的同一会话并始终先 plan。v3 writer bootstrap 是独立受认证 promotion action，但所有拓扑仍由服务端锁定：
-
-```bash
-numa app onboard --session <session-no> --spec <spec-file> --plan --json
-numa app apply <session-no> --idempotency-key <stable-key> --json
-numa app inspect <session-no> --watch --after-sequence <last-sequence> --json
-numa app publication attach <session-no> --source <git-root> --commit-message <message> --client-request-id <key> --idempotency-key <key> --yes --json
-numa app jenkins-binding confirm <session-no> --binding-id <id> --expected-version <version> --idempotency-key <key> --yes --json
-numa app writer-bootstrap ensure <session-no> --idempotency-key <key> --yes --json
-numa app observer-scope configure <session-no> --service-binding-id <id> --kustomization-namespace <ns> --kustomization-name <name> --helm-release-namespace <ns> --helm-release-name <name> --workload-namespace <ns> --workload-kind <kind> --workload-name <name> --expected-version <version> --idempotency-key <key> --yes --json
-numa app first-build decide <session-no> --decision defer --idempotency-key <key> --yes --json
-numa pipeline inspect <application-code> --json
-```
-
-GitOps structural apply 完成后，显式 `writer-bootstrap ensure` 让服务端在原 session/task 内执行
-`gitops-platform-writer-bootstrap/v2`。CLI 请求不含 repository/path/branch/YAML/binding/target/secret，
-并用 `app inspect` 续读 `GITOPS_V2_WRITER_BOOTSTRAP` 事件。事件必须证明 exact 三文件
-（base release、overlay values、overlay kustomization）的 contract/identity/revision/digest 都与原
-Application/repository/binding/target 匹配。`PENDING` 只继续读取同一 session；`UNKNOWN` 或任何 drift
-均 fail closed，不进入 Observer/first-build，不调用 legacy migration，不新建应用/会话/绑定/
-target，也不读取或修改 Secret。
-
-初始 POST 的 `UNKNOWN` 必须先只读检查同一 session，再只以原 Idempotency-Key 精确重放。普通
-inspect/status 与 first-build 未知结果恢复不会触发 bootstrap；只有已持久 child 本身为 UNKNOWN 时，
-用户才显式调用现有通用 session retry：
-
-```bash
-numa app inspect <session-no> --after-sequence <last-sequence> --json
-numa app writer-bootstrap ensure <session-no> --idempotency-key <original-key> --yes --json
-numa app retry <session-no> --json
-numa app inspect <session-no> --watch --after-sequence <last-sequence> --json
-```
-
-`app retry` 不接收新 run/key、SCM/path/Secret/first-build 参数，服务端只恢复原
-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`；独立 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：
-
-```bash
-numa jenkins platform-build-rollout plan enable-platform --application code-index --instance numa --shared-library-revision <approved-v2-shared-library-revision> --idempotency-key code-index-numa-v2-rollout-plan-1 --yes --json
-numa jenkins platform-build-rollout plan get <rollout-plan-no> --json
-numa jenkins platform-build-rollout apply --plan-no <rollout-plan-no> --plan-hash <64hex> --idempotency-key code-index-numa-v2-rollout-apply-1 --yes --json
-numa jenkins platform-build-rollout list --application code-index --instance numa --json
-numa jenkins platform-build-rollout get <rollout-no> --json
-numa jenkins platform-build-rollout configure <rollout-no> --expected-version <version> --idempotency-key code-index-numa-v2-auto-configure-1 --yes --json
-numa pipeline platform-build resolve --client-request-id <first-build-idempotency-key> --json
-numa pipeline platform-build status <request-id> --watch --json
-# 仅兼容旧部署/manual row 或 LEGACY rollout
-numa jenkins gitops-rollout readiness <legacy-rollout-no> --desired-mode legacy --expected-version <version> --operator-action-reference <change-record> --idempotency-key code-index-numa-legacy-readiness-1 --yes --json
-```
-
-v2 `platform-build-rollout` 所有写入要求 Idempotency-Key 与 `--yes`，且与旧 `gitops-rollout` 完全分离。automatic configure 前必须用 Project Publication CAS 发布只含 exact `@Library('mciShareLib@<approvedSharedLibraryRevision>') _` 与 `platformBuildEntry()` 的 Jenkinsfile，以及 strict `.mci/platform-build.yaml`；不能手工 Git push、改 global library、复用旧 `buildEntry()` 或使用 `mcexShareLib`。生产快照由 server-owned wrapper 执行，不加载应用 Jenkinsfile。configure 请求只含 `expectedVersion`，不接受 env/XML/Groovy/token/credential ID/value/operator attestation；v2 只要求平台 writer credential readiness，不要求 Jenkins Flux Git credential。首次 v2 build 不接受任意参数，productionReason 只留平台审计；未知 trigger 用 `platform-build resolve`，未知 stop 只读同一 request。旧 `gitops-rollout readiness` 固定为 `MANUAL_OPERATOR_ATTESTED`，不表示 Jenkins live-read。
-
-不要把数据库密码、SCM token 或其他 secret 放进 spec、delivery.parameters 或 build parameters。
-
-## 恢复规则
-
-- 保存 `sessionNo`、`revision`、`planHash`、idempotency key、last sequence。
-- 网络失败或结果未知时先使用正常 profile HTTPS 网关执行下面的只读恢复；同一次提交只复用原 idempotency key：
-
-  ```bash
-  numa repository status --client-request-id <original-id> --json
-  numa publication plan resolve --client-request-id <original-id> --json
-  numa publication status --client-request-id <original-id> --json
-  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。
-- standalone `publication plan create` 的 500/504、连接中断或无效 2xx 只触发原 key 有界 GET resolve，POST 只发一次；恢复结果必须是同 repository 的 `STANDALONE` plan。retryable 404 `PUBLICATION_PLAN_NOT_RESOLVED` 只允许稍后继续 GET。
-- 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 和上述恢复命令，等待平台恢复。
-
-命令块必须是可复制的真实 shell：续行只使用行尾反斜杠，禁止字面 diff `+`/`-` 前缀。
+结果未知时只读恢复原对象，不换 key 重放，不通过端口转发、SSH tunnel、直接 Jenkins API 或手工 Flux 写入绕过。

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

@@ -1,199 +1,33 @@
-# 应用创建与 Promote 工作流
+# Promote workflows
 
-## 目录
+## 已有远端仓库
 
-- [能力自述](#能力自述)
-- [源码状态路由](#源码状态路由)
-- [完整父状态机](#完整父状态机)
-- [安全与恢复](#安全与恢复)
-- [验收](#验收)
+确认团队、repository identity、默认 branch 与 immutable HEAD 后，复用同一 onboarding session 创建 Application、Jenkins Multibranch Job、binding 和 GitOps target/service binding。Job 创建使用 `INDEX_ONLY`，不得在入驻阶段触发构建。
 
-## 能力自述
-
-每次开始时基于运行时 command catalog 和 capability API 输出以下矩阵，不能依赖 skill 编写时的版本记忆：
-
-| 能力 | 证明方式 | 不可用时 |
-|---|---|---|
-| Repository plan/run | `repository capabilities` 与命令目录 | 停止仓库写入 |
-| Project Publication | 服务端规范 action `PLAN_PUBLICATION`，并由 command catalog 证明 `publication`、`app publication attach/resolve` 本地命令存在；`resolve` 不是独立服务端 action | 标记 `MANUAL_BRIDGE`，请求独立授权 |
-| Jenkins Job plan/run | job plan/provision/status 命令 | `WAITING_EXTERNAL`，不得直接调用 Jenkins |
-| Application onboarding | v2/v3 capabilities 与 plan | 不创建 Application |
-| GitOps plan/apply | target/profile/service 命令 | 保留已完成 child，停止部署 |
-| v3 writer bootstrap | `app writer-bootstrap ensure <same-session> --idempotency-key <key>` + 原 session status/events 中 exact `GITOPS_V2_WRITER_BOOTSTRAP` 证据 | 初始 POST 未知只以原 key 精确重放；已持久 child `UNKNOWN` 先 inspect，再用显式通用 `app retry <same-session>` 恢复原 run/key；drift fail closed |
-| Legacy image writer migration | `gitops service legacy-image-migration plan` 命令目录；不需要独立 server capability action | 保留 binding，不直写 YAML/path/image |
-| Platform build rollout v2 | `jenkins platform-build-rollout plan/apply/list/get/configure`；configure 必须自述 `JENKINS_API_VERIFIED/VERIFIED`；v2 无 manual readiness | 保持 fail-closed gate，不触发首次 build |
-| Jenkins GitOps rollout v1 | `jenkins gitops-rollout plan/apply/list/get/readiness`；`MANUAL_OPERATOR_ATTESTED` 不是 live-read | 仅用于旧应用，不隐式升级 v2 |
-| Observer scope/evidence | binding/scope/evidence read API | 不把 target 或 Application 声称为 ACTIVE |
-| Pipeline deploy | confirmed binding 与生产审批 | 不触发 build |
-
-能力自述必须说明：当前 skill 可以安全完成哪些步骤、哪些步骤需要管理员、哪些步骤会触发外部写入，以及这次默认不会执行什么。
-Application onboarding 以 `numa app capabilities --json` 的服务端动作自述为准，并与
-`numa commands --json` 交叉验证；命令存在而服务端返回 501 时标记 `UNAVAILABLE`。
-
-## 源码状态路由
-
-### REMOTE_TRACKED
-
-1. 解析 remote 到平台 connection/repository。
-2. 读取 provider externalId、default branch 和 remote HEAD。
-3. 要求本地 clean HEAD 与远端目标 HEAD 一致。
-4. 生成 `USE_EXISTING`/`REGISTER_EXISTING` plan 或直接使用受管 repositoryRef。
-
-### LOCAL_HISTORY_WITHOUT_REMOTE
-
-适用于已有提交历史、clean HEAD、无任何 remote 的项目：
-
-1. 从 Jenkins `APP_NAME`、包名和目录名推断 application code；冲突时停止确认。
-2. 查询 SCM connection、namespace、同名 remote、CREATE capability 和初始化限制。Codeup 先用
-   `numa app scm inspect <code> --json` 或 `numa repository connection list --json` 读取一等安全 readiness；
-   只有 `codeupCredentialReadinessAvailable=true` 才解释 configured 布尔值。availability=`false`/缺失都
-   保持 unknown，不从 `capabilities.executableMode` 推断 credential。
-3. 生成 Repository `CREATE` plan。仓库名默认等于稳定 application code，visibility 默认 PRIVATE。初始化方式必须来自 provider capability：Codeup 无空仓安全首次提交能力时使用受管 `README` 初始化，再由 publication CAS 更新同一 `README.md` 并创建其余清单文件；不得先建空仓再绕过控制平面推送。
-4. 本地只读生成受限 publication manifest；manifest 锁定 source HEAD、mode、文件数量、总字节、每文件 digest 和整体 digest，不包含内容或凭据。若包含 `100755` 且 provider=Codeup，安全连接摘要必须同时证明 `codeupCredentialReadinessAvailable=true` 与 `codeupCloneCredentialConfigured=true`；availability=`true` 下显式 false 是 missing，availability=`false`/缺失都是 unknown，二者都以 `PUBLICATION_EXECUTABLE_MODE_UNSUPPORTED` 停止。`codeupAccessTokenConfigured=true` 只证明 OpenAPI 可用，不能把 Personal AT 当 HTTPS Git 密码。
-5. 用 `app begin` 取得 session 后，在同一 session 创建 schemaVersion=3 onboarding parent plan；固定 `mode=NEW`、catalog/repository=`CREATE_NEW`、project=`PUBLISH_PROJECT`，并引用绑定该 session 的 Repository plan/ref。Repository child 完成后 parent 停在 `WAITING_EXTERNAL / ATTACH_PUBLICATION_PLAN`，此时才用 `app publication attach` 上传受控 bundle；服务端把 child consumer 固定为 `APPLICATION_ONBOARDING/<sessionNo>`，验证 parent planHash 和同一 manifest digest。客户端不能自报 consumer、remote URL、branch 或 provider credential。
-6. 远端创建或提交结果未知时复用同一 idempotency key，通过 run/events reconcile；不能直接重放成第二个仓库或第二次提交。
-7. 读回 remote HEAD/tree evidence 后继续同一个 onboarding session；不得另建 `ATTACH_EXISTING` 会话，也不得把独立 `STANDALONE` publication plan 附着到 parent。
-
-若 publication API 尚未发布，仍生成完整计划并标记 `MANUAL_BRIDGE`。只有用户单独确认后才能使用本机 Git 身份推送；推送前后必须验证 remote URL、branch、HEAD，且不得把 credential 写入命令、remote URL 或日志。人工桥接不是 skill 的默认路径，也不能被报告成平台闭环。
-
-### DIRTY_WORKTREE / UNVERSIONED_DIRECTORY
-
-- dirty 时只列出变更数量，不读取敏感文件；停止 apply，让用户决定提交范围。
-- 非 Git 目录只能选择受管模板 NEW，或先由用户建立明确版本历史；不要自动 `git init`/commit。
-
-## 完整父状态机
+## 本地历史但没有 remote
 
 ```text
-DISCOVER_AND_CLASSIFY
-BEGIN_APPLICATION_SESSION
-PLAN_REPOSITORY
-PLAN_APPLICATION_V3
-RUN_APPLICATION_PARENT
-RUN_REPOSITORY_CHILD
-WAIT_ATTACH_PUBLICATION_PLAN
-ATTACH_PROJECT_PUBLICATION_PLAN
-RUN_PROJECT_PUBLICATION_CHILD
-VERIFY_REMOTE_HEAD
-PLAN_JENKINS_JOB
-RUN_JENKINS_JOB_NO_BUILD
-SYNC_INVENTORY_AND_CONFIRM_BINDING
-PLAN_LEGACY_IMAGE_WRITER_MIGRATION_IF_REQUIRED
-WAIT_AUTHENTICATED_MIGRATION_APPLY
-PLAN_GITOPS_STRUCTURE
-WAIT_AUTHENTICATED_GITOPS_APPLY
-WAIT_INTERNAL_GITOPS_V2_WRITER_BOOTSTRAP
-PLAN_AND_APPLY_JENKINS_GITOPS_ROLLOUT
-VERIFY_MANAGED_JENKINSFILE_EXACT_MCI_SHARE_LIB_PIN
-WAIT_JENKINS_API_VERIFIED_AUTOMATIC_CONFIGURE
-CONFIGURE_OBSERVER_SCOPE
-WAIT_FLUX_OBSERVER_ATTESTATION
-WAIT_EXPLICIT_FIRST_BUILD
-COMPLETED
+app begin
+-> Repository CREATE plan（consumer=APPLICATION_ONBOARDING/<sessionNo>）
+-> schemaVersion=3 CREATE_NEW + PUBLISH_PROJECT
+-> Repository child SUCCEEDED
+-> app publication attach（同一 session 与 parent planHash）
+-> Publication child SUCCEEDED
+-> 继续 canonical Jenkins/GitOps 初始化
 ```
 
-已部署应用可采用 `ATTACH_APPLICATION`，但必须验证团队、repository、Jenkins 与运行态身份一致。Candidate adopt 不得创建一个与 onboarding reservation 冲突的第二个 Application。
-
-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
-
-新应用 v2 不运行 legacy migration。先在原 onboarding session 内完成 v2 Job provenance replan 和
-GitOps structural apply，随后显式执行 `app writer-bootstrap ensure`，由 onboarding v3 服务端执行
-`gitops-platform-writer-bootstrap/v2`。该阶段只读写服务自己的 base release、exact overlay values 和
-overlay kustomization 三个文件；不枚举、不读取也不改写 sibling raw Secret，也不新建
-Application、session、binding 或 target。CLI 不接受任意仓库/path/YAML/branch/secret，只续读原 session 的
-`GITOPS_V2_WRITER_BOOTSTRAP` 事件；`PENDING` 只等待，`UNKNOWN` 或 contract/identity/revision/digest
-drift 都禁止 Observer/first-build。旧 v1 应用只有在确有 writer pointer 缺失时才使用 legacy migration。
-初始 POST 为 `UNKNOWN` 时先 inspect 原 session，并只以原 Idempotency-Key 精确重放 bootstrap action；
-只有已持久 child 本身为 UNKNOWN 时，用户才显式执行 `numa app retry <same-session> --json`。该通用恢复
-只让服务端续作原 run/key，不创建新 child 或身份；status/inspect 与 first-build 未知结果恢复保持纯读。retry 后仍为 UNKNOWN 或存在
-drift 时继续阻断，不重放 first-build POST，也不手工写 SCM。
-`code-index` 目标仍是原 target=`prd`、Jenkins instance=`numa`；旧批准提交
-`230e0f...` 是 v1，不得用于 v2 plan。v2 必须等新的 clean shared-library 40hex 发布后再执行：
-
-```bash
-numa jenkins platform-build-rollout plan enable-platform --application code-index --instance numa --shared-library-revision <approved-v2-shared-library-revision> --idempotency-key code-index-numa-v2-rollout-plan-1 --yes --json
-numa jenkins platform-build-rollout plan get <rollout-plan-no> --json
-numa jenkins platform-build-rollout apply --plan-no <rollout-plan-no> --plan-hash <64hex> --idempotency-key code-index-numa-v2-rollout-apply-1 --yes --json
-numa jenkins platform-build-rollout get <rollout-no> --json
-numa jenkins platform-build-rollout configure <rollout-no> --expected-version <version> --idempotency-key code-index-numa-v2-auto-configure-1 --yes --json
-# 原 onboarding session 的 first-build action 内部触发 v2；未知时用独立只读入口恢复
-numa pipeline platform-build resolve --client-request-id <first-build-idempotency-key> --json
-numa pipeline platform-build status <request-id> --watch --json
-# 仅兼容旧部署/manual row 或 LEGACY rollout
-numa jenkins gitops-rollout readiness <legacy-rollout-no> --desired-mode legacy --expected-version <version> --operator-action-reference <change-record> --idempotency-key code-index-numa-legacy-readiness-1 --yes --json
-```
-
-rollout apply 只持久化 gate，不连接 Jenkins、不改全局配置、不触发 build。automatic configure 前必须
-证明受管 Jenkinsfile 已由 Project Publication CAS 发布 exact
-只含 `@Library('mciShareLib@<approvedSharedLibraryRevision>') _` 与 `platformBuildEntry()`，并同时发布 strict `.mci/platform-build.yaml`；未完成时回到 Publication plan，不能手工
-Git push、改 Jenkins global library、复用旧 `buildEntry()` 或用 `mcexShareLib`。生产快照使用 server-owned wrapper，不执行应用 Jenkinsfile。configure 请求只含 `expectedVersion`，不接收
-env/XML/Groovy/token/credential ID/value/operator attestation；只输出服务端派生 public tuple、credential 配置
-booleans、observed shared-library revision、verified source revision、Jenkinsfile/build-profile/configuration digest 与 `READY/JENKINS_API_VERIFIED/VERIFIED`。verified source revision 是源码快照，不要求等于 approved library revision。旧 readiness 是
-trusted manual attestation compatibility，不是 live-read。
-
-v2 platform-build 不接受任何 `--param`，生产审批依据只进入平台审计；Jenkins 只构建镜像并提交一次
-image intent，不持有 Flux Git credential，不运行 kubectl。DevOps server 在 contract/build/stop 同一锁下
-执行 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 手改目标。
-2. 优先由 secret owner 迁到目标集群已登记的 ExternalSecret 或 SealedSecret provider，再重新生成受治理 plan。
-3. 只有目标集群确认没有任何已登记 provider 时，才可把保留现有 Secret 的动作作为显式受审两阶段桥。第一阶段必须使用 clean、受控的 Flux 仓库，为现有 Flux-managed Secret 资源增加 `kustomize.toolkit.fluxcd.io/prune: disabled`，reconcile 后用 Observer/live evidence 验证目标集群同一 Secret 的 annotation 已生效。
-4. 第二阶段使用独立变更单移除 raw Secret manifest/reference，再次 reconcile，并验证同一 Secret 仍存在且未被 prune。随后由 secret owner 轮换所有曾进入 Git 历史的值；桥接不等于已消除泄露。
-5. 两阶段及轮换分别要求明确 owner、变更单和审批，不能复用应用创建/promote 的笼统确认。本地 `mci-flux` dirty、目标 Secret 身份不唯一、annotation/live evidence 不足或任一步结果未知时均 fail closed，不能继续 migration、rollout 或首次 build。
+默认不直接 `git remote add` 或 `git push`。只有平台 publication 能力不可用且用户单独授权时才使用人工桥接。
 
-## 安全与恢复
+## Jenkins 与 GitOps
 
-- CLI 从不接受 SCM/Jenkins credential 参数；凭据由平台引用。
-- publication 拒绝 `.git`、凭据文件、Secret、symlink、socket/device、绝对/父路径和超限 bundle。
-- Codeup Personal AT 只证明 OpenAPI 能力；包含 `100755` 的 tree 还要求平台已托管独立 HTTPS clone username/password。只读检查普通 `app scm` 或顶层 repository connection 返回的 `codeupCredentialReadinessAvailable=true` 和 `codeupCloneCredentialConfigured=true`；availability=`false`/缺失是 unknown，availability=`true` 下显式 false 才是 missing，两者都以 `PUBLICATION_EXECUTABLE_MODE_UNSUPPORTED` 停止。不要用 `codeupAccessTokenConfigured` 或 `capabilities.executableMode` 代替，也不要读取 admin/credential。
-- 需要管理员补齐 Codeup credential 时，交互操作使用 `app scm rotate ... --credential-prompt` 原生隐藏输入；不要让用户通过聊天提供值，也不要生成 Python/getpass 管道。非交互操作保留 chmod 600 文件或重定向 stdin。
-- 每个 child 保存 plan/hash、run number、idempotency key、last event sequence；onboarding publication child 只能通过 session-scoped bridge 创建。
-- HTTP 2xx 后 schema 解析失败属于结果未知；先 list/status/get，不能直接重放。
-- legacy migration plan 没有 Idempotency-Key/resolve-by-key，未知结果必须 fail closed。Rollout plan 也不按 key resolve；apply 只在写前 baseline 之后出现 exact application/instance/plan mode 且新 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`，`STALE/DRIFTED/UNAVAILABLE` 或证据不足均 result unknown；旧 readiness 只在同 rollout 出现 exact reference/mode/status/identity 且新 version 时恢复。预存 READY/LEGACY 不构成证据。
-- 普通 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。
+- Jenkinsfile 使用全局共享库提供的 `gitopsBuildEntry()`，不固定或调用退役快照入口。
+- Multibranch root 经受管 plan/apply 创建或接管，使用 `INDEX_ONLY` 发现 branch child。
+- inventory 同步后确认 application-to-job binding。
+- GitOps structural apply 必须产生该服务的目标 values/kustomization 结构和 service binding；不得写入原始 Secret。
+- 新 branch child 第一次运行不带业务参数，或传 `INIT=true` 强制初始化。
+- 初始化成功后用新的幂等键和明确 `ENV_ID` 执行实际部署。
+- 生产发布必须交给 `numa-jenkins-deployment` 做独立授权与三方核验。
 
-## 验收
+## 恢复
 
-- 远端仓库唯一，默认分支、visibility、owner team 与确认一致。
-- remote commit/tree 与 publication manifest evidence 一致。
-- Application 只创建/接管一个，Repository 关系正确。
-- Multibranch Job 配置 digest 与计划一致，未意外触发 build。
-- Jenkins binding 为 CONFIRMED，目标 branch 可构建。
-- onboarding v3 在 GitOps structural apply 后已以同一 session/task 产生 exact `GITOPS_V2_WRITER_BOOTSTRAP` 成功证据；contract 为 `gitops-platform-writer-bootstrap/v2`，三文件及 identity/revision/digest 无 drift。
-- 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 未三方一致时，不得把运行态部署成功描述为完整平台发布成功。
+Repository、Publication、Jenkins 和 onboarding 写响应未知时只读取原 clientRequestId/session/run。不得换 key 重放、创建影子 Job、第二 Application、第二 binding，或手工改写 Flux。

package/skills/numa-create-application/scripts/inspect-project.mjs

@@ -223,7 +223,7 @@ const result = {
     jenkinsfile: fileSet.has('Jenkinsfile'),
     jenkinsVariables,
     buildEntry: /\bbuildEntry\(\)/u.test(jenkins),
-    platformBuildEntry: /\bplatformBuildEntry\(\)/u.test(jenkins),
+    gitopsBuildEntry: /\bgitopsBuildEntry\(\)/u.test(jenkins),
     dockerfile: fileSet.has('Dockerfile'),
     dockerExposedPorts: [...dockerfile.matchAll(/^EXPOSE\s+([^\r\n#]+)/gmu)].map((match) => match[1].trim()),
     hasCompose: fileSet.has('compose.yaml') || fileSet.has('docker-compose.yml')