@numa-tech/numa 1.13.2 → 1.13.4

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

@@ -0,0 +1,232 @@
+# Numa CLI 执行契约
+
+## 目录
+
+- [命令解析](#命令解析)
+- [只读发现](#只读发现)
+- [安全输出](#安全输出)
+- [入驻执行](#入驻执行)
+- [恢复规则](#恢复规则)
+
+## 命令解析
+
+优先使用 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 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 scm`，但仓库生命周期必须使用顶层 Repository Control Plane：
+
+```bash
+numa repository remote list --connection <connection-code> --search <repository-name> --json
+```
+
+团队选项可见不等于当前用户具有 `MEMBER+`。通过运行时 command catalog 找团队成员查询能力；缺失时用批准的只读平台 API，并把无法证明的成员资格标记为 `UNRESOLVED`。
+
+## 安全输出
+
+`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。
+
+attach 的 POST 返回 500/504、连接中断或 2xx body 无法解析时，CLI 必须用原值有界轮询精确只读
+resolve endpoint；手工恢复命令为：
+
+```bash
+numa app publication resolve <session-no> --client-request-id <original-id> --json
+```
+
+该命令不上传 bundle、不重放 attach。200 必须是同一 session 的 `APPLICATION_ONBOARDING` binding
+且 `replayed=true`；retryable 404 `ONBOARDING_PUBLICATION_PLAN_NOT_RESOLVED` 表示可稍后重查，不能
+改用新 key 或新 session。
+
+## 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
+```
+
+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": "NONE"
+    },
+    "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：
+
+```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 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
+```
+
+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` 并提供真实审批证据。
+
+legacy Jenkins image writer 迁移与 rollout 是两个独立 gate。只有现有 overlay 缺 writer pointers 时才在 GitOps materialize/apply 前做 migration；普通 GitOps plan 已产生合规 pointers 时跳过。当前 `code-index` 生产 target 是 `prd`、Jenkins instance 是 `numa`、approved shared-library commit 是 `230e0f00444dfd1874e1ab3e624381341a0c31c5`；当前没有 service binding，migration plan 不带 `--service-id`：
+
+```bash
+numa gitops service legacy-image-migration plan --application code-index --target prd --profile MCI_FLUX_V1 --json
+numa gitops service apply <migration-plan-number> --plan-hash <64hex> --idempotency-key code-index-prd-image-migration-1 --yes --json
+numa jenkins gitops-rollout plan enable-platform --application code-index --instance numa --shared-library-revision 230e0f00444dfd1874e1ab3e624381341a0c31c5 --idempotency-key code-index-numa-rollout-plan-1 --yes --json
+numa jenkins gitops-rollout plan get <rollout-plan-no> --json
+numa jenkins gitops-rollout apply --plan-no <rollout-plan-no> --plan-hash <64hex> --idempotency-key code-index-numa-rollout-apply-1 --yes --json
+numa jenkins gitops-rollout list --application code-index --instance numa --json
+numa jenkins gitops-rollout get <rollout-no> --json
+numa jenkins gitops-rollout readiness <rollout-no> --desired-mode platform --expected-version <version> --operator-action-reference <change-record> --idempotency-key code-index-numa-readiness-1 --yes --json
+```
+
+migration plan 只接受 stable references，不接受 YAML/path/image/secret；READY 后复用 `gitops service apply`。rollout 所有写入要求 Idempotency-Key 与 `--yes`。`readiness` 由 CLI 从 GET 回传 exact tuple，固定为 `MANUAL_OPERATOR_ATTESTED`，不接受 secret/XML/env map/credential value，也不表示 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 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
+  ```
+
+  CLI 只有在写前 event cursor 之后观察到与本次 planHash/精确 intent 匹配的新持久事件时，才可能返回 `recovered_from_status=true`；既有 `WAITING_EXTERNAL` 或旧输出字段不能作为恢复证据。Repository、Publication、Jenkins 的 resolved run 还必须匹配请求 planNo 和响应中可用的稳定 workload identity。
+- 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 恢复；readiness 必须用同 rollout 的 exact reference/mode/status/identity/new version 恢复。预存 READY/LEGACY 不是成功证据。
+- `WAITING_EXTERNAL` 使用 `resume`；可重入失败使用 `retry`；HEAD 移动使用 `reassess`。按服务端 recovery action 选择，不自行跳步骤。
+- 生产 `pipeline build`、stop、retry 需要独立审批 ID 或具体 production reason；本 skill 默认只创建/核验流水线。
+- 不启动或遗留 `kubectl port-forward`、SSH tunnel 或后台代理来绕过网关；只读恢复仍失败时报告 profile/API origin、request ID 和上述恢复命令，等待平台恢复。
+
+命令块必须是可复制的真实 shell：续行只使用行尾反斜杠，禁止字面 diff `+`/`-` 前缀。

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

@@ -0,0 +1,134 @@
+# 应用创建与 Promote 工作流
+
+## 目录
+
+- [能力自述](#能力自述)
+- [源码状态路由](#源码状态路由)
+- [完整父状态机](#完整父状态机)
+- [安全与恢复](#安全与恢复)
+- [验收](#验收)
+
+## 能力自述
+
+每次开始时基于运行时 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，停止部署 |
+| Legacy image writer migration | `gitops service legacy-image-migration plan` 命令目录；不需要独立 server capability action | 保留 binding，不直写 YAML/path/image |
+| Jenkins GitOps rollout | `jenkins gitops-rollout plan/apply/list/get/readiness` 命令目录；readiness 必须自述 `MANUAL_OPERATOR_ATTESTED` | 保持 fail-closed gate，不触发首次 build |
+| 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 和初始化限制。
+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，安全连接摘要必须证明 `codeupCloneCredentialConfigured=true`；否则以 `PUBLICATION_EXECUTABLE_MODE_UNSUPPORTED` 停止，不能把 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。
+
+## 完整父状态机
+
+```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
+PLAN_AND_APPLY_JENKINS_GITOPS_ROLLOUT
+WAIT_TRUSTED_MANUAL_READINESS
+CONFIGURE_OBSERVER_SCOPE
+WAIT_FLUX_OBSERVER_ATTESTATION
+WAIT_EXPLICIT_FIRST_BUILD
+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`，要求真实审批依据。
+
+### Legacy writer 与 Jenkins rollout gate
+
+当只读证据证明现有 overlay 缺少 Jenkins writer pointers 时，migration 是受治理 GitOps materialize/apply 的前置。如果普通 GitOps plan 已生成合规 pointers，则不执行 migration。当前 `code-index`
+的生产事实为 target=`prd`、Jenkins instance=`numa`、approved shared-library commit=
+`230e0f00444dfd1874e1ab3e624381341a0c31c5`；当前没有 service binding，因此 plan 不得猜测
+`--service-id`：
+
+```bash
+numa gitops service legacy-image-migration plan --application code-index --target prd --profile MCI_FLUX_V1 --json
+numa gitops service apply <migration-plan-number> --plan-hash <64hex> --idempotency-key code-index-prd-image-migration-1 --yes --json
+numa jenkins gitops-rollout plan enable-platform --application code-index --instance numa --shared-library-revision 230e0f00444dfd1874e1ab3e624381341a0c31c5 --idempotency-key code-index-numa-rollout-plan-1 --yes --json
+numa jenkins gitops-rollout plan get <rollout-plan-no> --json
+numa jenkins gitops-rollout apply --plan-no <rollout-plan-no> --plan-hash <64hex> --idempotency-key code-index-numa-rollout-apply-1 --yes --json
+numa jenkins gitops-rollout get <rollout-no> --json
+numa jenkins gitops-rollout readiness <rollout-no> --desired-mode platform --expected-version <version> --operator-action-reference <change-record> --idempotency-key code-index-numa-readiness-1 --yes --json
+```
+
+migration plan 请求不接受 YAML/path/image/secret/credential，CLI 也不输出文件 path/diff/pointer。
+rollout apply 只持久化 gate，不连接 Jenkins、不改全局配置、不触发 build。readiness 是
+trusted manual attestation，不是 live-read；CLI 从 GET 响应回传 exact tuple 与 credential reference names，
+不接收 credential value、raw XML 或 env map。
+
+## 安全与恢复
+
+- CLI 从不接受 SCM/Jenkins credential 参数；凭据由平台引用。
+- publication 拒绝 `.git`、凭据文件、Secret、symlink、socket/device、绝对/父路径和超限 bundle。
+- Codeup Personal AT 只证明 OpenAPI 能力；包含 `100755` 的 tree 还要求平台已托管独立 HTTPS clone username/password。只读检查安全 readiness boolean，缺失时以 `PUBLICATION_EXECUTABLE_MODE_UNSUPPORTED` 停止，不把 AT 当 Git password。
+- 每个 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 时恢复；readiness 只在同 rollout 出现 exact reference/mode/status/identity 且新 version 时恢复。预存 READY/LEGACY 不构成证据。
+- 普通 profile HTTPS 网关失败时，Repository/standalone Publication/Jenkins 先按原 clientRequestId 查 `status`，普通 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。
+- Jenkins scan 不等于 build；观察到意外 build 时停止父流程并报告。
+- GitOps target 只有 topology validation 时保持 DRAFT；Jenkins attestation 最多推进 VERIFYING，只有独立 Flux Observer evidence 能推进 ACTIVE。
+
+## 验收
+
+- 远端仓库唯一，默认分支、visibility、owner team 与确认一致。
+- remote commit/tree 与 publication manifest evidence 一致。
+- Application 只创建/接管一个，Repository 关系正确。
+- Multibranch Job 配置 digest 与计划一致，未意外触发 build。
+- Jenkins binding 为 CONFIRMED，目标 branch 可构建。
+- GitOps service binding 和 exact Observer scope 存在；configRevision 与 observedRevision 一致后才 ACTIVE。
+- 未经独立生产授权不得触发 build；触发后必须以 Jenkins 终态和 Flux/Observer evidence 验收。

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

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+
+const root = resolve(process.argv[2] ?? process.cwd());
+if (!existsSync(root) || !statSync(root).isDirectory()) {
+  process.stderr.write('Project directory does not exist or is not a directory.\n');
+  process.exit(2);
+}
+
+const excludedDirectories = new Set([
+  '.git', '.idea', '.next', '.nuxt', '.output', '.turbo', '.venv',
+  '.superpowers', '.worktrees', 'coverage', 'dist', 'node_modules', 'out',
+  'target', 'test-results'
+]);
+const sensitiveNames = /^(?:\.env(?:\..*)?|.*(?:secret|credential|private[-_.]?key|token).*)$/iu;
+const maximumFiles = 5_000;
+const maximumDepth = 7;
+const files = [];
+
+function walk(directory, depth = 0) {
+  if (depth > maximumDepth || files.length >= maximumFiles) return;
+  let entries = [];
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (files.length >= maximumFiles) break;
+    if (entry.isDirectory()) {
+      if (!excludedDirectories.has(entry.name) && !sensitiveNames.test(entry.name)) {
+        walk(join(directory, entry.name), depth + 1);
+      }
+      continue;
+    }
+    if (entry.isFile() && !sensitiveNames.test(entry.name)) files.push(join(directory, entry.name));
+  }
+}
+
+walk(root);
+const relativeFiles = files.map((file) => file.slice(root.length + 1));
+const fileSet = new Set(relativeFiles);
+
+function text(relativePath, maximumBytes = 1_000_000) {
+  if (!fileSet.has(relativePath)) return null;
+  try {
+    const value = readFileSync(join(root, relativePath));
+    return value.byteLength <= maximumBytes ? value.toString('utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+function json(relativePath) {
+  const value = text(relativePath);
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function git(args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 2_000_000
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeRemote(value) {
+  if (!value) return null;
+  try {
+    const parsed = new URL(value);
+    parsed.username = '';
+    parsed.password = '';
+    parsed.search = '';
+    parsed.hash = '';
+    return parsed.toString();
+  } catch {
+    return value
+      .replace(/^[^@\s]+@([^:]+):/u, '$1:')
+      .replace(/([?&](?:access_?token|token|password|secret)=)[^&#\s]+/giu, '$1[REDACTED]');
+  }
+}
+
+function slug(value) {
+  return String(value ?? '')
+    .trim()
+    .replace(/^@[^/]+\//u, '')
+    .replace(/\.git$/u, '')
+    .split(/[/:]/u)
+    .at(-1)
+    ?.toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '') || null;
+}
+
+const packageFiles = relativeFiles.filter((file) => /(^|\/)package\.json$/u.test(file));
+const manifests = packageFiles.flatMap((file) => {
+  const value = json(file);
+  return value && typeof value === 'object' ? [{ file, value }] : [];
+});
+const rootPackage = manifests.find((entry) => entry.file === 'package.json')?.value ?? null;
+const dependencies = new Set();
+for (const { value } of manifests) {
+  for (const section of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    for (const name of Object.keys(value[section] ?? {})) dependencies.add(name);
+  }
+}
+
+const jenkins = text('Jenkinsfile') ?? '';
+const dockerfile = text('Dockerfile') ?? '';
+const jenkinsVariables = {};
+for (const key of ['APP_NAME', 'APP_HOME', 'BUILD_FLOW', 'TRIGGER_BUILD', 'NODE_VERSION', 'JDK_VERSION', 'SONAR_SCAN']) {
+  const match = jenkins.match(new RegExp(`\\b${key}\\s*=\\s*["']([^"']+)["']`, 'u'));
+  if (match) jenkinsVariables[key] = match[1];
+}
+
+const remoteNames = (git(['remote']) ?? '').split(/\r?\n/u).filter(Boolean);
+const remotes = remoteNames.map((name) => ({
+  name,
+  url: sanitizeRemote(git(['remote', 'get-url', name]))
+}));
+const primaryRemote = remotes.find((item) => item.name === 'origin') ?? remotes[0] ?? null;
+const statusLines = (git(['status', '--porcelain', '--untracked-files=all']) ?? '')
+  .split(/\r?\n/u).filter(Boolean);
+const branch = git(['branch', '--show-current']);
+const head = git(['rev-parse', 'HEAD']);
+const upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+const isGitRepository = git(['rev-parse', '--is-inside-work-tree']) === 'true';
+const trackedPathCount = (git(['ls-files', '-z']) ?? '').split('\0').filter(Boolean).length;
+const executableTrackedPathCount = (git(['ls-files', '-s', '-z']) ?? '')
+  .split('\0')
+  .filter((entry) => entry.startsWith('100755 '))
+  .length;
+const sourceState = !isGitRepository ? 'UNVERSIONED_DIRECTORY'
+  : statusLines.length > 0 ? 'DIRTY_WORKTREE'
+    : remoteNames.length === 0 && head ? 'LOCAL_HISTORY_WITHOUT_REMOTE'
+      : remoteNames.length > 0 && !upstream ? 'REMOTE_WITHOUT_UPSTREAM'
+        : 'REMOTE_TRACKED';
+
+const technologies = [];
+function technology(code, evidence) {
+  technologies.push({ code, evidence });
+}
+if (fileSet.has('pom.xml')) technology('java-maven', 'pom.xml');
+if (fileSet.has('settings.gradle.kts') || fileSet.has('build.gradle.kts')) technology('java-gradle', 'Gradle Kotlin DSL');
+if (fileSet.has('go.mod')) technology('go', 'go.mod');
+if (fileSet.has('pyproject.toml')) technology('python', 'pyproject.toml');
+if (dependencies.has('@nestjs/core')) technology('nestjs', '@nestjs/core dependency');
+if (dependencies.has('next')) technology('nextjs', 'next dependency');
+if (dependencies.has('nuxt')) technology('nuxt', 'nuxt dependency');
+if (dependencies.has('fastify')) technology('fastify', 'fastify dependency');
+if (dependencies.has('express')) technology('express', 'express dependency');
+if (dependencies.has('vite')) technology('vite', 'vite dependency');
+if (rootPackage && technologies.length === 0) technology('node', 'package.json');
+
+const databaseSignals = [];
+const databasePackages = new Map([
+  ['pg', 'POSTGRESQL'], ['postgres', 'POSTGRESQL'], ['drizzle-orm', 'SQL'],
+  ['@prisma/client', 'SQL'], ['mysql2', 'MYSQL'], ['mariadb', 'MYSQL'],
+  ['mongodb', 'MONGODB'], ['mongoose', 'MONGODB'], ['better-sqlite3', 'SQLITE'], ['sqlite3', 'SQLITE']
+]);
+for (const [name, engine] of databasePackages) {
+  if (dependencies.has(name)) databaseSignals.push({ engine, evidence: `dependency:${name}` });
+}
+for (const file of relativeFiles) {
+  if (/\/(?:drizzle|prisma|migrations?)\//u.test(`/${file}`)) {
+    databaseSignals.push({ engine: 'UNKNOWN_SQL', evidence: `path:${file}` });
+    if (databaseSignals.length >= 20) break;
+  }
+}
+
+const packageManager = fileSet.has('pnpm-lock.yaml') ? 'pnpm'
+  : fileSet.has('yarn.lock') ? 'yarn'
+    : fileSet.has('package-lock.json') ? 'npm'
+      : fileSet.has('bun.lockb') || fileSet.has('bun.lock') ? 'bun' : null;
+const remoteSlug = slug(primaryRemote?.url);
+const packageSlug = slug(rootPackage?.name);
+const appCodeCandidate = slug(jenkinsVariables.APP_NAME) ?? remoteSlug ?? packageSlug ?? slug(basename(root));
+
+const result = {
+  schemaVersion: 1,
+  scan: {
+    directoryName: basename(root),
+    filesConsidered: relativeFiles.length,
+    truncated: files.length >= maximumFiles,
+    maximumDepth,
+    sensitiveFilesRead: false
+  },
+  application: {
+    codeCandidate: appCodeCandidate,
+    evidence: jenkinsVariables.APP_NAME ? 'Jenkinsfile:APP_NAME'
+      : remoteSlug ? 'git:primary-remote' : rootPackage?.name ? 'package.json:name' : 'directory-name',
+    packageName: rootPackage?.name ?? null
+  },
+  git: {
+    repository: isGitRepository,
+    sourceState,
+    branch: branch || null,
+    head: head || null,
+    upstream: upstream || null,
+    dirty: statusLines.length > 0,
+    changedPathCount: statusLines.length,
+    trackedPathCount,
+    executableTrackedPathCount,
+    remotes
+  },
+  build: {
+    packageManager,
+    packageFiles,
+    technologies,
+    jenkinsfile: fileSet.has('Jenkinsfile'),
+    jenkinsVariables,
+    buildEntry: /\bbuildEntry\(\)/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')
+  },
+  database: {
+    signals: databaseSignals,
+    recommendation: databaseSignals.length === 0 ? 'NONE'
+      : databaseSignals.some((item) => item.engine === 'POSTGRESQL') ? 'POSTGRESQL'
+        : databaseSignals.every((item) => item.engine === databaseSignals[0]?.engine) ? databaseSignals[0]?.engine : 'REVIEW'
+  },
+  deployment: {
+    hasHelm: relativeFiles.some((file) => /(^|\/)Chart\.ya?ml$/u.test(file)),
+    hasKubernetesManifests: relativeFiles.some((file) => /(^|\/)(?:k8s|kubernetes|helm)\//u.test(file)),
+    hasCloudflareWorker: relativeFiles.some((file) => /(^|\/)wrangler(?:\.[^.]+)?\.(?:toml|jsonc?)$/u.test(file))
+  }
+};
+
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);