@numa-tech/numa 1.13.2 → 1.13.3

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

@@ -0,0 +1,126 @@
+# 应用入驻确认清单
+
+## 目录
+
+- [状态模型](#状态模型)
+- [完整字段](#完整字段)
+- [草案格式](#草案格式)
+- [最终确认](#最终确认)
+
+## 状态模型
+
+每项记录 `value`、`state`、`confidence`、`evidence`、`requiredBefore`：
+
+- `OBSERVED`：权威事实；
+- `INFERRED`：推荐值，等待确认；
+- `CONFIRMED`：用户确认；
+- `UNRESOLVED`：阻止 plan/apply；
+- `DEFERRED`：当前能力未提供，不得声称已配置。
+
+`requiredBefore` 使用 `PLAN`、`APPLY`、`FIRST_DEPLOY` 或 `FUTURE_DATABASE_PROVISION`。
+
+## 完整字段
+
+### 目标和身份
+
+- Numa version、profile ID、API origin、tenant、目标环境级别；
+- runtime command catalog、`app capabilities` 与各 child capability 状态；
+- 当前用户 subject/username/email；
+- 平台角色、团队成员关系及最低所需成员级别；
+- 操作范围：仅 plan、创建应用/仓库/流水线、是否触发 build/deploy。
+
+### 应用归属
+
+- application code、name、description/status；
+- teamId/team code、成员资格证据；
+- systemId/system code；
+- business-domain ID/code；
+- owner/maintainer 联系边界。
+
+### 项目和代码库
+
+- 本地目录、技术语言/框架、构建系统；
+- Git dirty 状态、branch、HEAD、remote；
+- source state：REMOTE_TRACKED/LOCAL_HISTORY_WITHOUT_REMOTE/REMOTE_WITHOUT_UPSTREAM/DIRTY_WORKTREE/UNVERSIONED_DIRECTORY；
+- mode：NEW/EXISTING；repoMode：STANDALONE/ADD_MODULE；
+- SCM connection/provider/organization；
+- repository namespace/name/externalId/defaultBranch/expectedHead/visibility；
+- 模板 code/revision、技术栈 code、模板参数；
+- 缺仓库时的创建、首次提交和推送策略。
+- publication manifest/version/digest、文件数/总字节、排除项、plan/run/idempotency key；
+- executable tracked file count；Codeup HTTPS clone credential readiness（只记录 boolean）；
+
+### 构建和流水线
+
+- MCI build-flow、APP_NAME、APP_HOME、agent label、Node/JDK/Python version；
+- PORT=8080、启动入口、健康检查；
+- Jenkinsfile/Dockerfile 策略；
+- jenkinsRequired、tiers、trigger branch、manual/webhook；
+- build parameters（仅非敏感）、Sonar、artifact/image name；
+- 是否只创建流水线，是否触发 build/deploy。
+- Jenkins Job plan/run/config digest、inventory generation、binding confirmation；
+
+### 环境和运行位置
+
+- defaultEnvironmentId/env code/tier；
+- clusterId/name、region、tenant/network zone、architecture；
+- Kubernetes namespace、replicas、resource profile；
+- GitOps target/profile/service plan、binding、Observer scope 与 live evidence；
+- ingress/domain、service port、readiness/liveness；
+- 与数据库/外部依赖的网络可达性。
+
+### 数据库
+
+- needed、engine/version、shared/dedicated；
+- instanceId/code/name、environment/region/network；
+- database name、schema、owner role；
+- HA/replicas/storage、backup/retention；
+- migration tool/owner；
+- secret injection mechanism（只记录引用方式，不记录 secret）；
+- capability：AVAILABLE 或 `DEFERRED`。
+
+### 治理和恢复
+
+- onboarding sessionNo/revision/planHash/idempotency key；
+- Repository、Publication、Jenkins、GitOps、Observer 各 child plan/run 和 last event sequence；
+- 预期外部副作用；
+- 生产审批需求；
+- blocking warnings、恢复动作和回滚边界。
+- 写响应是否由原响应确认或由写前 cursor 之后、精确匹配本次 intent 的新持久证据恢复；既有状态不得标为 `recovered_from_status`。publication attach 必须记录原 sessionNo/clientRequestId、resolve 200 same-session binding/replayed=true，或 retryable 404 待恢复状态；禁止的 port-forward/tunnel 旁路。
+
+## 草案格式
+
+先输出紧凑表格：
+
+| 类别 | 参数 | 建议/事实 | 状态 | 置信度与证据 |
+|---|---|---|---|---|
+| 应用 | code | `order-service` | INFERRED | HIGH：Jenkins APP_NAME |
+| 归属 | teamId | `12 / payments` | UNRESOLVED | MEDIUM：同系统应用多数归属 |
+| 环境 | envId | `2 / dev1` | INFERRED | HIGH：唯一 active DEVELOP 环境 |
+| 数据库 | instanceId | — | DEFERRED | 数据库 CLI 尚未提供 |
+
+表格后列出：
+
+1. 可直接采用的观察值；
+2. 推荐决策及原因；
+3. 本轮要问的问题；
+4. 当前 blockers；
+5. 未来能力待办。
+
+## 最终确认
+
+执行前用以下顺序展示：
+
+1. **身份与目标**：谁、在哪个 profile/tenant、操作哪个环境；
+2. **应用归属**：code/name/team/system/domain；
+3. **代码库**：provider/connection/repo/branch/HEAD，以及是否创建和推送；
+   本地无 remote 时另列 publication manifest digest、bundle 边界和是否需要人工桥接；
+4. **技术与构建**：stack/template/build-flow/8080/health；
+5. **部署位置**：envId/cluster/namespace/tier；
+6. **数据库**：engine/instance/database/schema，明确 AVAILABLE 或 DEFERRED；
+7. **将发生的写操作**：逐项编号；
+8. **不会发生的操作**：默认包括 build、production deploy 和 secret 写入；
+9. **恢复信息**：session/idempotency key/结果未知处理；
+10. **未决告警**：必须为空才允许 apply；`DEFERRED` 项需明确不影响本次 apply。
+
+最后只提供“确认执行（推荐，仅在清单无 blocker 时）”和“返回修改”两类选择。用户确认后仍要做一次只读漂移检查。

package/skills/numa-create-application/references/inference-rules.md

@@ -0,0 +1,69 @@
+# 参数推断规则
+
+## 目录
+
+- [证据优先级](#证据优先级)
+- [应用和团队](#应用和团队)
+- [代码库](#代码库)
+- [技术栈](#技术栈)
+- [环境和集群](#环境和集群)
+- [数据库](#数据库)
+
+## 证据优先级
+
+按以下顺序使用证据：平台权威 API > 已提交仓库配置 > Git remote/HEAD > 用户明确描述 > 命名约定。冲突时展示冲突，不自动选低优先级值。
+
+置信度建议：唯一权威映射为 HIGH；两个独立证据一致为 MEDIUM/HIGH；仅名称相似为 LOW。LOW 值必须询问。
+
+## 应用和团队
+
+- 应用 code 优先取已存在 catalog code，其次 Jenkins `APP_NAME`，再取 remote 仓库 slug，最后取根 package/project 名。
+- code 使用小写 kebab-case；不要静默改动已部署镜像名或稳定 API 标识。
+- 应用团队代表业务/运维责任，不等同于 Codeup group、Keycloak group 或 Kubernetes namespace。
+- 团队候选依次参考：已有同系统应用、CODEOWNERS/maintainer、仓库 namespace、package scope、当前用户团队成员关系。
+- 只推荐当前用户至少具有平台要求成员级别的团队。成员关系无法证明时必须询问或停止。
+- systemId 优先复用同一产品族的系统；business domain 只提供背景，不能替代 systemId。
+
+## 代码库
+
+- 已有 remote 且平台 SCM 能返回同一仓库时使用 `EXISTING`，固定 `externalId`、default branch 和 `expectedHead`。
+- remote 不存在但平台有同名仓库时，先确认是否接管；不得只凭名字认领。
+- 没有代码库时，从应用 code 推断 repository name，从已确认团队/系统推断 namespace；检查名称冲突和 SCM create capability。
+- 已有 clean Git HEAD 但 remote 列表为空时分类为 `LOCAL_HISTORY_WITHOUT_REMOTE`。它不是受管模板 NEW：先锁定同 application code 的私有 Repository CREATE plan（Codeup 使用受管 README 初始化），再创建 schemaVersion=3 parent，并通过 session-scoped Publication child 发布现有 tree；继续同一 session，不转成第二个 ATTACH_EXISTING。
+- Jenkins `APP_NAME`、线上镜像/HelmRelease 名称和目录名冲突时，优先稳定运行身份；目录名只作为低优先级线索。不得因此创建两个远端仓库。
+- 新仓库优先私有、默认分支 `main`，除非组织标准或现有项目明确使用其他分支。
+- 模板为空或 SCM 没有 CREATE capability 时，不绕过 Numa 直接造目录记录。给出缺少模板、连接、权限或仓库的前置清单。
+- 工作区不干净、无 commit 或 HEAD 与远端不一致时，不创建基于该 HEAD 的流水线。
+- publication capability 不可用时标记 `MANUAL_BRIDGE`，不要把普通 `git push` 伪装成平台自动化。人工桥接必须单独确认并读回 remote HEAD。
+
+## 技术栈
+
+- 从构建文件、依赖和产物识别实际框架，再与 `numa` 返回的 technology stack 匹配。
+- 不把通用 Fastify/Express 项目伪装成 NestJS，也不把 Vite SPA 伪装成 Next.js。
+- 没有精确 stack 时显示实际检测结果和最接近候选，要求用户确认平台映射或先注册 stack。
+- 创建前检查 MCI 构建标准：Jenkins `buildEntry()`、APP_NAME、构建节点、8080/PORT、启动入口和 Dockerfile 保留理由。
+
+## 环境和集群
+
+- envId 只能来自 Numa/platform 权威环境列表，不能从 `dev1`、`stg1`、`prod` 字符串自行构造 ID。
+- 未明确要求生产时优先推荐可用的 DEVELOP 环境；不得默认生产。
+- 集群优先选择 envId 显式绑定的 active/ready 集群；其次匹配 tenant、region、网络区和 workload class。
+- 同一 env 有多个集群时比较容量、架构、合规标签、数据库网络可达性和现有同系统应用分布，并询问用户。
+- 一等 cluster CLI 不存在时，通过已批准的只读 API收集候选；没有权威数据时标记 `DEFERRED`，不要编造 clusterId。
+- namespace 默认候选为应用 code，但必须检查平台命名策略和冲突。
+
+## 数据库
+
+先判断是否需要持久化：
+
+- 没有 ORM/driver/migration/config 信号时推荐 `NONE`。
+- `pg`、PostgreSQL URL、Drizzle/Postgres migration 等信号推荐 PostgreSQL。
+- `mysql2`/MariaDB 信号推荐 MySQL；Mongo driver/Mongoose 推荐 MongoDB；SQLite 只默认用于本地开发，不能自动当作生产数据库。
+
+数据库清单至少包含：engine、version、shared/dedicated、instanceId、database name、schema、owner、environment、region/network、HA、backup/retention、migration owner、secret injection。不得推断密码或连接串。
+
+- PostgreSQL shared instance 推荐独立 database role 和独立 schema；schema 候选为应用 code 转 snake_case，限制在 63 bytes 内。不要默认使用 `public`。
+- PostgreSQL dedicated database 可让 database name 与应用 code 的 snake_case 一致，但 database 和 schema 仍分别确认。
+- MySQL 的 schema 与 database 通常同义，在清单中明确标注。
+- instanceId 必须来自平台数据库 inventory。当前 CLI 无该能力时标记 `DEFERRED`，同时保留期望 engine/schema/环境供以后升级。
+- 数据库选择必须与目标 env/cluster 网络可达性一致。先确认 env/cluster，再最终选择 instance。

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

@@ -0,0 +1,216 @@
+# 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": "primary",
+      "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` 并提供真实审批证据。
+
+不要把数据库密码、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。
+- `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,105 @@
+# 应用创建与 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，停止部署 |
+| 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_GITOPS_STRUCTURE
+WAIT_AUTHENTICATED_GITOPS_APPLY
+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`，要求真实审批依据。
+
+## 安全与恢复
+
+- 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，不能直接重放。
+- 普通 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 验收。