@stalfh233/omc-cli 0.0.0-stage → 0.4.10

package/skills/omc-capability-scouting.md

@@ -0,0 +1,55 @@
+---
+name: omc-capability-scouting
+description: Scout a NEW CloudPivot config face honestly. Use when a capability isn't in the coverage manifest yet and you must prove it before promising it.
+---
+
+# Capability Scouting (扒配置方法论)
+
+How to scout a new CloudPivot configuration face honestly: the output feeds the
+coverage manifest, and a manifest promise is always evidence-backed.
+
+## Phase 0 — 定面
+
+Name the face first. The same Chinese/English word often names two engines
+(businessrule B-plane vs field-level dataRuleType; app-tree node id vs schema
+record id). The wrong face wastes everything after it.
+
+## Phase 1 — 静态三角定位
+
+1. **Enum scan** — the platform is enum-driven. The `*Type.java` enums are the
+   complete universe of a concept.
+2. **Endpoint chain** — Controller → FacadeImpl → Service along the lifecycle
+   (save/publish/delete/get_*). The gate methods ("when is this refused") are
+   half the contract.
+3. **DTO archaeology** — decompiled model fields and defaults are the request
+   shape; chase nested options JSON to leaf types.
+4. **Designer cross-check** — search the admin dist chunks by control code,
+   label, or write-mapping. The UI's write-mapping is the true wire contract.
+5. **DB persistence face** — the `h_*` tables are final truth; the API face
+   leaks. A dbsweep once caught orphans invisible to every API.
+
+## Phase 2 — 合同成形
+
+6. Grade every fact: `observed` (from source lines) vs `inferred` (from chunk
+   reverse-engineering). Keep the confidence tiers apart.
+7. Split open points into statically-closeable vs live-only.
+8. Design negative controls — a contract has discriminative power only when a
+   forged payload is refused for the right reason.
+
+## Phase 3 — live 收口
+
+9. Treat the static contract as a hypothesis and interrogate it live, item by
+   item — half the wire facts in this project came from live corrections
+   (gateway double-prefix, int enums, Void envelope, tree-node ids,
+   form/load as authoritative readback).
+10. Prefer a real traffic sample; capture designer requests when possible.
+11. Guard against false PASS: read the full green chain; "called" ≠ "passed".
+12. Before blaming the platform, retry with a different authoritative id
+    source and compare against designer traffic.
+
+## Output
+
+Per open point: evidence (file+lines / chunk anchor) → conclusion
+(observed/inferred) → verdict; close with a go/no-go and the residual
+human-decision list. A capability enters the coverage manifest only with live
+evidence; everything else stays `blocked` / `static-only` / `unsupported`.

package/skills/omc-config-draft-review.md

@@ -0,0 +1,171 @@
+---
+name: omc-config-draft-review
+description: Draft-before-write protocol — use before ANY CLI write (model, field, form, view, data rule, business rule, workflow, service, data). Present the intended design in plain language and get explicit human approval first; revise the draft freely while it is unapproved. This is the human gate; the environment writable permission is the machine gate.
+---
+
+# Draft Review (草稿确认) — the human gate before every write
+
+The agent owns the design; the CLI materialises it. **Before any write call**,
+present a plain-language draft of exactly what will be written and wait for
+explicit approval. An unapproved draft is free to revise; nothing touches the
+environment until the human says write.
+
+This skill is the conversational human gate. The machine-side permission check
+comes after it: `writable:false` refuses, and a production write additionally
+requires `confirmProduction:true`:
+
+```
+先定参数 → 由参数生成草稿 → 人工确认 → 写入 → 读回核对
+                                        (写前你已确认的，就是即将发出的那份参数)
+```
+
+## 0. Approval lifecycle — package granularity, interruption, one notice
+
+- **粒度 = 变更包（master approval）**：一份草稿枚举本包全部增删改（含清理），逐条列出；
+  人工一次批准授权**整包**顺序执行。批一次 ≠ 看不清 —— 每一条都必须在草稿里可见。
+- **中断作废**：执行中断（断网、会话重启、停损保留）后，已获的批准**随之作废**；
+  恢复执行剩余步骤前必须**重新出草稿、重新获准**。看不见的时段里不得有旧批准继续生效。
+- **一次收口报告（run completion notice）**：一个 run 只在结束（或最后动作完成）时发
+  一条结构化收口报告（做了什么/结果/残留）；中间步骤不打扰用户。执行过程中的说明是
+  协调信息，不是通知。
+
+## 1. Unit — one coherent change per draft
+
+One draft per coherent change (e.g. "build the inspection model + its form").
+A single draft may cover **several** designs; group them by **design surface**:
+
+| 节 | 设计域 | 对应写工具 |
+| --- | --- | --- |
+| 模型 | 模型设计 | `model.create` / `model.delete` |
+| 字段 | 表单字段设计 | `field.create` / `field.update` / `field.publish` |
+| 表单 | 表单设计 | `form.draft` / `form.publish` |
+| 数据规则 | 字段级数据规则 | `datarule.create` / `update` / `delete` |
+| 业务规则 | 业务规则配置（触发器+图） | `rule.save` / `rule.enable` / `configure_rule` |
+| 视图 | 列表视图设计 | `listview.create` / `configure` / `delete` |
+| 流程 | 流程设计 | `workflow.create` / `update` / `publish` / `bindRule` |
+| 在线JS | 表单脚本 | `onlinejs.compose`（唯一可用；`draft`/`publish` 已冻结、调用即拒） |
+| 服务 | 后端服务注册 | `service.register` / `service.delete` |
+| 数据 | 运行时数据（夹具） | `data.save` / `submit` / `update` / `delete` |
+
+**Every write entry point takes this gate — low-level atoms and the high-level
+`configure_model` / `configure_form` / `configure_rule` alike.**
+
+## 2. Language — Chinese design prose, codes on identity keys
+
+- Field/control **types in Chinese**: 短文本、长文本、数值、日期、单选、多选、
+  下拉、复选、关联单选、关联多选、人员单选、部门单选、附件、地址、超链接、布尔、公式…
+- Relations say **what maps where**, e.g.
+  `设备（device） 关联单选 → 设备台账（eq_device），带出 设备名称（deviceName）`.
+- **Attach the code for identity keys** (model schemaCode, field code, choice
+  values, relation target code) — these are written verbatim and can collide.
+  Pure display labels may omit the code.
+- Each section is headed with its design surface + the tool it maps to, so the
+  reviewer can point at one section precisely.
+
+## 3. Draft template
+
+```
+目标：<一句话业务目的>
+环境：<environment>   应用：<application code>
+
+> 选应用前先 `discover_environment` 看它的门户分组归属：若 `portalHidden:true`
+> （落在兜底分组 code=all，或分组解析不到），门户按具名分组渲染、该应用不可见——
+> 先用 `app.update {code, groupId}` 迁入具名分组，再动工。别只在接口里确认应用存在。
+
+【模型设计】          (model.create)
+  · OMC走查（omc_mcp_walk）  类型：列表
+
+【表单字段设计】      (field.create → field.publish)
+  · 编号（walk_no）     短文本        列表显示
+  · 数量（walk_qty）    数值
+  · 类别（walk_cat）    单选  选项：一类 / 二类 / 三类
+  · 备注（walk_remark） 长文本        非必填
+
+【表单设计】          (form.draft → form.publish)
+  · 默认表单，编码 = 模型 code（omc_mcp_walk）
+  · 布局：标题 + 系统行（创建人/创建时间/单据号）+ 业务分组
+  · 控件：类别 必填；其他默认；字段按上序一行一个
+
+【业务规则配置】      (rule.save → rule.enable)
+  · 触发：数据事件 新增（提交后）
+  · 图：开始 → 完成态守卫(guardProjectEditable) → 计算实际产出(actualOutput) → 系统新增 → 结束
+  · 入映射：申报金额(declaredAmount) → declaredAmount，信用等级(creditLevel) → creditLevel
+  · 出映射：actualOutput → actualOutput
+  · 铁律：动作节点排在系统节点之前（否则输出不落库）
+
+【视图设计】          (listview.configure)
+  · 列：编号 / 数量 / 类别
+  · 条件：类别 下拉；排序：编号 倒序
+  · 按钮：沿用平台默认（新增 / 删除）
+
+【流程设计】          (workflow.create → update → publish → bindRule)
+  · 模板：开始 → 审批节点（审批人：<角色>）→ 结束
+  · 绑定：提交事件 → <ruleCode>
+
+【清理授权】          (data.delete / rule.delete / model.delete)
+  · 验收后删除：本条数据、该规则、模型 omc_mcp_walk（清单外对象另行报备）
+```
+
+## 4. Review flow
+
+1. Agent posts the draft(s) and asks **“确认写入 / 需要修改？”**
+2. Reviewer answers:
+   - **确认** (nothing named) → the whole batch is approved → write.
+   - **点名要改第 N 张** → **整批挂起**，只改那张，改完重新全批过。
+3. **先定参数 → 由参数生成草稿**：草稿里的类型/code/目标/映射，必须就是要发出的
+   参数值；不要先写一段话、执行时另拼参数。
+4. After writing: **read back and compare**. If the readback differs from the
+   approved draft, **stop and report** — never silently accept or auto-retry.
+
+## 5. Fingerprint re-check
+
+A draft carries the environment fingerprint captured when it was written.
+**Before executing an approved draft, re-check that fingerprint**; if it
+changed, the draft is void — re-discover and re-present. No machine token
+enforces this anymore, so the check is an explicit agent step, not a refusal
+you can wait for.
+
+## 6. Exemptions
+
+- **空转写**（读回证明本次写不会改变任何字段/结构，如重复发布已发布表单）免草稿，
+  报一行「无变更」即可。**只要任一处会变，就回到完整草稿。**
+- **免草稿开关只由人工主动说**（如「本轮免草稿」）才生效；agent 不得自行提议或默认。
+  豁免仅限**本轮新建的 `omc_mcp_*` 夹具**；**删除既有对象、改真实域，永不豁免**。
+  豁免期间每步仍报一行「做了什么」。
+- **预授权任务书（自治执行）**：当你在**非交互**上下文运行（被委派的子代理 / 批处理 / 一次
+  性任务），且任务书本身就是一份完整变更包、并声明已批准（如项目 `AGENTS.md` 写明
+  「本基准任务书即已批准的需求草稿，可直接执行」）时——**任务书即草稿即批准**：执行前按
+  §3 粒度把变更包原样列一遍作为记录，然后**直接写入**。**不要停下来问「确认写入」**：
+  非交互上下文没有人类回合会回答，等待 = 永久停滞（实测：子代理因此空转到任务失败）。
+  范围以任务书为界，任务书之外的增删改仍需新草稿。指纹重核与写后读回照旧。
+  此豁免**要求任务书显式声明预授权**；agent 不得自行把交互会话当成自治上下文。
+
+## 7. Cleanup
+
+清理授权捆在创建授权里：创建草稿写明「验收后删除这些」，确认即一并授权。
+**清单外的对象仍要单独出草稿。** 清理只碰自有 `omc_mcp_*` 夹具。
+
+## 8. Canonical configuration order（规范配置顺序）
+
+```
+0. 选定应用并确认门户分组可见（discover_environment 的 portalHidden）
+1. model.create                （被引用的目标模型最先建）
+2. field.create                （全部字段；关联字段带 displayField + displayFieldType）
+3. field.publish               （模型级：一次发布该模型全部草稿字段）
+4. form.draft → form.publish   （脚手架依赖已发布字段；重跑必须带 fieldCodes）
+5. listview.create/configure   （依赖已发布字段；query/update 自动 publish=TRUE，无 draft→publish 两态）
+6. rule.save → rule.enable     （保存 ≠ 发布 ≠ 可见；enable 才 publish+启用，或 rule.save 传 publish:true）
+7. workflow（依赖模型与字段就绪）
+```
+
+视图与表单脚手架都从**发布面**读字段元数据——字段未发布，列/控件就生成不出来。
+`data.list` 对未配列的自定义字段投影为 null（显示面缺配置，不是数据缺失）；核值用 `data.load`。
+字段级变更（如关联展示字段）改完后，必须重走 `form.draft` → `form.publish` 运行时才生效（表单控件快照字段 options）。
+
+## Invariants
+
+- 未确认不写入；改任何一张 = 整批暂停，重新全批通过才写。
+- 批准跟着变更包走：一次批准一整包；中断后批准作废，恢复需重新草稿、重新确认。
+- 草稿里的身份键带 code；类型用中文；关联写明映射目标。
+- 执行前重核环境指纹，变了就重出草稿；写后读回核对。
+- 一个 run 只发一次收口报告；生产环境可写但每笔必须显式带 `confirmProduction:true`。

package/skills/omc-five-piece-flow.md

@@ -0,0 +1,35 @@
+---
+name: omc-five-piece-flow
+description: The CLI governed change process — use for any CloudPivot write (model, field, form, rule, workflow, data, service). discover → draft → permission check → execute → readback/cleanup.
+---
+
+# Five-Piece Flow (五件套流程)
+
+**五件套** — every governed change runs the same five pieces. High-level tools
+orchestrate them; low-level tools expose each piece as one atom.
+
+1. **Discover (发现)** — `discover_environment` / `environment.fingerprint`.
+   Applications, models, fields, forms; the environment fingerprint. Discovery
+   precedes every write.
+2. **Draft (草稿)** — present the design as plain-language change package and
+   get explicit human approval through `omc-config-draft-review`.
+3. **Permission check (权限检查)** — `writable:false` refuses before wire;
+   `production:true` additionally requires the write call to carry
+   `confirmProduction:true`. `dryRun` previews the exact plan without writing.
+4. **Execute (执行)** — call the write tool once. The governance chain runs
+   (semantic gate → coverage gate → environment permission → version gate →
+   production confirmation → write lease), then authoritative readback. Success
+   records `deliveryState: DELIVERED`.
+5. **Read back & clean up (读回与清理)** — prove the state with read tools;
+   delete owned fixtures and confirm exact absence. The delivery ends CLEANED
+   only when absence is proven.
+
+## Invariants
+
+- `writable` is the only environment write permission; no approval token or
+  self-approval setting exists.
+- `uncertain` ≠ `ok`. A transport failure freezes; re-discover before retrying.
+- Production is writable when `writable:true`, but every production write must
+  carry `confirmProduction:true` and records `productionConfirmed:true`.
+- Cleanup touches owned fixtures only (prefix `omc_mcp_`) and exits with zero
+  residue.

package/skills/omc-glossary.md

@@ -0,0 +1,86 @@
+---
+name: omc-glossary
+description: OMC and CloudPivot terminology. Consult when a term is unclear — 环境指纹, 覆盖清单, 交付态, bizsheet, Void envelope, or a result status.
+---
+
+# OMC Glossary (术语表)
+
+Terminology for the `omc` configuration CLI. Built on CloudPivot 8.6 (anchor
+8.6.26); other versions/product lines are accepted in compatibility mode with a
+`versionNotice`.
+
+## Core nouns
+
+- **CloudPivot (云枢)** — the low-code platform being configured. The CLI
+  drives its design-time and runtime APIs over HTTPS.
+- **Environment profile (命名环境)** — a named CloudPivot connection record
+  (baseUrl + applicationCode + optional engineCode, default marker, production
+  risk label, writable permission) in `omc.config.json`. Non-default
+  environments must be selected explicitly (`environment` argument, `OMC_ENV`,
+  or project `.omc-env`).
+- **Multi-tenant engineCode (多租户租户码)** — the profile's optional
+  `engineCode`. On a multi-tenant deployment
+  (`systemConfig.options.multiTenancy === true`) the gateway routes by the
+  `x-lowcode-enginecode` header, which OMC sends on every request; without it
+  the gateway answers 404 (even for `/api/public/system/config`). Leave it unset
+  on single-tenant deployments.
+- **Environment write permission (环境写权限)** — the profile's `writable`
+  boolean. False refuses every write before wire; true permits writes subject to
+  coverage, version, semantic, and production-confirmation gates.
+- **Production confirmation (生产确认)** — the per-write `confirmProduction:true`
+  acknowledgement required when the selected profile is marked production. It
+  records `productionConfirmed:true`; it is not a second configuration key.
+- **Credential store (凭据存储)** — `~/.config/omc/credentials`, mode 0600.
+  Never packaged, never echoed, never logged. `OMC_CLOUDPIVOT_CREDENTIAL`
+  (JSON) takes priority.
+- **Environment fingerprint** — canonical sha256 of (environment name,
+  authoritative origin, application code, enterprise id). Identifies the
+  environment in plans and audit artifacts; it is not an approval-token binding.
+- **Coverage manifest (覆盖清单)** — the machine-readable M1 manifest vendored
+  at `coverage/m1-coverage-manifest-v1.json`. The tool surface is bounded by
+  it; out-of-coverage calls reject citing the entry.
+- **Write lease (写租约)** — per-environment serialization of write
+  operations inside one server process.
+- **Delivery state (交付态)** — DELIVERED (write + authoritative readback
+  recorded) → VERIFIED (agent verified readback) → CLEANED (fixture
+  removed, exact absence proven).
+
+## CloudPivot domain nouns
+
+- **Model (.bizmodels)** — design-time schema; LIST or TREE. Physical
+  delete is proven; there is no separate model-publish wire call (a model
+  reaches its usable state via field/form publication).
+- **Field (bizproperty)** — model property. Draft → publish two-face
+  lifecycle; draft face `isPublish=false`, published face `isPublish=true`.
+- **Field families (字段族)** — live-accepted types: text-extension,
+  people-department, address-attachment, dictionary-enum, relevance,
+  numeric-logical, date-time (+ formula EXPRESSION-only).
+- **Default form (bizsheet)** — the model's own sheet. Draft-first:
+  `bizsheet/update` saves the draft (publishedHtmlJson carried explicitly),
+  then `bizsheet/publish` publishes.
+- **Business rule (businessrule)** — B-plane rule graph. B1 dead-state
+  rules and B1.2 CRUD/conditional node graphs; enable = publish by rule id.
+- **Online JS** — form-level custom script embedded in the published form:
+  compose (preserves the platform skeleton) → publish; the authoritative
+  readback is `onlinejs.compose` returning the read-back publishedHtmlJson
+  with a SHA-256 fingerprint. (There is no `get_source`/programming tool —
+  that removed face authored backend Java, not form Online JS.)
+- **M2 runtime data** — `runtime/form/save|load|delete`, `query/list` (CLI
+  tools `data.save` / `data.load` / `data.submit` / `data.update` / `data.list`).
+  `data.load` is the authoritative custom-field readback; list projection
+  is a pinned boundary (custom fields keys-present-values-null).
+- **B2 service (bizservice)** — service + method registration face.
+- **List view (query)** — design-time list-view header lifecycle with
+  forced LIST/showOnPc/unpublished defaults.
+- **Void envelope** — CloudPivot responses are `{errcode, errmsg, data}`;
+  errcode 0 with `data: null` is a success with no payload.
+
+## Result vocabulary
+
+- `ok` — performed and authoritatively read back.
+- `refused` — governance or coverage refusal; nothing executed. Citations
+  name the manifest entry.
+- `uncertain` + `frozen: true` — transport outcome cannot be established
+  (outage/timeout). Never treated as success; re-discover before retrying.
+- `dry-run` — a validated plan is returned with zero environment writes; rerun without dry-run to execute when the environment permits it.
+- `production-confirmation-required` — a writable production environment refused a write because the call omitted `confirmProduction:true`.

package/skills/omc-refusals.md

@@ -0,0 +1,110 @@
+---
+name: omc-refusals
+description: Decode a refused or uncertain OMC result. Use when a call returns refused/uncertain, or a status looks wrong, to find what the blocker means and the correct next action. Grouped by family, not enumerated per code.
+---
+
+# Refusals & Recovery (拒绝与恢复)
+
+Grouped by family. For a specific tool's exact wire and valid shapes, follow the
+`contract`/`describe` pointers; this page is the **meaning + next action**.
+
+Read `result.blocker` (refused) or `result.status`+`result.reason` (uncertain).
+`result.retryable` is advisory only — the family decides what to do.
+
+## 1. Write permission declined
+
+- `environment-write-disabled` — the environment profile has `writable:false`.
+  **Do not retry the same call.** Either the operator turns writes on in
+  `omc setup`, or the write is out of bounds. Zero wire was sent.
+- `production-confirmation-required` — the target is production and the call
+  omitted `confirmProduction:true`. If the human approved a production write,
+  re-send with `confirmProduction:true`; otherwise **stop**. Zero wire was sent.
+
+## 2. Boundary — the capability is not covered
+
+- `capability-out-of-coverage` — `result.citation` names the manifest entry and
+  its status (`blocked` / `unsupported` / `static-only`). **The refusal is the
+  answer.** Do not route around it with a lower-level tool; the boundary is the
+  same. If it should be covered, use `omc-capability-scouting`.
+- `version-family-evidence-missing` — no version evidence could be parsed at all;
+  writes fail closed. (A version that simply isn't 8.6 is **not** a refusal any
+  more: OMC is built on 8.6 but accepts other versions/product lines in
+  compatibility mode, surfacing a `versionNotice`; only truly absent evidence
+  still fails closed.) Verify the environment's version before retrying.
+
+## 3. Semantic preflight — the payload is malformed
+
+Refused **before any wire call**; fix the payload, don't retry as-is. The refusal
+usually carries `validation` entries to fix one by one.
+
+- `business-code-invalid`, `duplicate-field`, `duplicate-service`,
+  `dictionary-create-duplicate`, `app-create-duplicate`, `model-create-duplicate`
+- `field-*` family gates (unaccepted family, missing relation `relativeCode`,
+  nested child table, OCR/ELECTRONIC_SIGN)
+- `form-layout-invalid`, `form-fieldcodes-unknown`, `form-html-render-invalid`
+- `rule-graph-validation-failed`, `rule-graph-*` (node-graph dry lint)
+- `datarule-options-invalid`, `datarule-property-not-published`, `datarule-duplicate-property-type`
+- `listview-*` (columns/buttons/sorts/gantt/presentation)
+- `configure-model-*`, `apply-changes-tool-not-atomic`, `apply-changes-step-failed`
+- `bizservice-*` (required field, name length, config invalid, category/dbconnpool)
+- `model-type-immutable`, `model-referenced-by`
+
+### 3b. A platform `errcode` is a SHAPE error, never a boundary
+
+`blocker:"wire-business"` + non-zero `errcode` means the payload's shape (or a
+referenced dependency) is wrong — **not** that the capability is unavailable.
+Fix the shape; never conclude 「配置表达不了 → 必须二开」 from an errcode.
+Known shape codes: `300010` a node resolves its input schema from `inputParam`
+and it is missing (BRANCH/UPDATE/CREATE/DELETE/ASSIGN/BIZ_ACTION/MESSAGE/QUERY;
+`prepareRuleGraph` defaults `"_input"`) or a node names a non-existent schema;
+`550018` a referenced field/out-param/mapping key is absent; `50000` a
+condition/expression/query shape is off. Compare against
+`omc describe <tool> --example …` and the node-graph prose, then re-save.
+Escalate to 二开 **only** for a real `capability-out-of-coverage` (§2).
+
+## 4. Readback mismatch — the write landed but does not match
+
+`*-readback-failed`, `*-readback-mismatch`, `cleanup-absence-readback`,
+`intent-readback-mismatch`, `workflow-render-readback-invalid`.
+
+**Stop and report.** Never auto-retry, never assume success. Inspect
+`result.readback` / `result.verification.differences`, compare against the
+approved draft, and decide with the human. A second write may duplicate.
+
+## 5. Dependency & async convergence
+
+- `model-referenced-by` — inbound relation references block the delete. Clean up
+  **dependency-inverted**: delete referencing models first, then the referenced
+  one.
+- `absent:false` + `treeNodePending:true` with `nextAction:"wait-and-recheck"` —
+  the platform's per-column cascade is still running (40–60s). **Not a failure.**
+  Wait ~60s and re-run; the call is idempotent and `already-absent` short-circuits.
+
+## 6. Idempotency & replay
+
+- A repeated `requestId` with identical args returns `replay:"already-completed"`
+  — the first write stands; treat as success, do not re-execute.
+- `intent-plan-tampered` — the plan file changed after planning. Re-run
+  `intent plan`.
+- `intent-baseline-drifted` — the environment moved after planning. Re-run
+  `intent plan` against the fresh baseline.
+- `intent-plan-environment-mismatch` — the plan targets a different environment.
+
+## 7. Transport uncertainty — outcome unknown
+
+`status:"uncertain"` with `frozen:true` (`cli-timeout`, `batch-timeout-budget`,
+`wire-transport:*`). The write **may** be in flight.
+
+1. Read back the affected resource (or `artifact get <id>` / the `requestId`).
+2. Only after the outcome is established, decide whether to retry.
+3. Never blind-retry — that risks a second write.
+
+`write-lock-held` — another write holds the environment lock; `owner` and
+`recovery` are included. Wait for it to clear (it auto-recovers when the holding
+process exits), then retry. This guards concurrency, not approval.
+
+## 8. Input / target
+
+- `tool-input-invalid` — schema violation (exit 10); fix the arguments.
+- `dictionary-target-required`, `intent-plan-invalid` — a required selector or
+  shape is missing; see `describe <tool>`.

package/skills/omc-requirement-analysis.md

@@ -0,0 +1,161 @@
+---
+name: omc-requirement-analysis
+description: Turn a fuzzy Chinese requirement into a platform-independent Configuration Intent. Use before discovery when the ask is vague or spans domains.
+---
+
+# Requirement Analysis (需求分析)
+
+Turn a fuzzy Chinese requirement into a platform-independent **Configuration
+Intent** before any discovery, plan, or draft.
+
+This is reasoning, not a governed tool: it reads no environment, prints no
+credential, and writes nothing.
+
+**Leading word: 定面** — name the face. The same Chinese word names several
+OMC surfaces (规则, 表单, 字段, 集成, 在线, 数据). 定面 first; everything after
+depends on it. This word is shared with `omc-capability-scouting`.
+
+## Process
+
+Five moves, in order. Each ends on a completion criterion.
+
+### 1. 定面 — name the face
+
+For every noun in the requirement, assign exactly one OMC face from the 定面表.
+
+**Done when** every ambiguous noun carries exactly one face, and every noun
+with no face is marked a boundary.
+
+### 2. 归类 — capability and lane
+
+Map each face to its capability, lane, and status in the 能力表.
+
+**Done when** every face has a capability, its lane, and one status
+(`executable` / `partial` / `blocked` / `unsupported`).
+
+### 3. 选路 — implementation path
+
+Choose one path per behavior, in preference order: **native** →
+**configuration + Online JS** → **configuration + backend extension**.
+
+**Done when** each behavior carries a path, and every non-native path names
+the code owner and why native cannot carry it.
+
+### 4. 澄清 — risk-driven
+
+Ask only about unresolved details that change behavior, data, environment
+impact, or acceptance (see 澄清触发). A blocked or unsupported face is a
+**boundary** — stated, not asked. All other detail takes the established
+project convention.
+
+**Done when** the open-question list is emitted, or empty.
+
+### 5. 出意图 — emit Configuration Intent
+
+Emit the intent object (see Configuration Intent).
+
+**Done when** every field is populated and `nextStep` is set.
+
+## 定面表 — disambiguate before classifying
+
+| 需求里的词 | 面 A | 面 B | 判别 |
+| --- | --- | --- | --- |
+| 规则 | cross-model **businessrule** graph (B 平面) | 字段级控件规则 `dataRuleType` 3/4/5 | 跨模型/触发/动作 → businessrule；单字段随值必填/只读/显示 → 表单控件绑定 |
+| 表单 | default form **(`bizsheet`)** | list view **(`query`)** | 录入/详情/布局/控件 → default form；列表/视图/筛选列 → list view |
+| 字段 | model property **(`bizproperty`)** | form control binding | 结构/类型 → model field；可见/只读/必填 → form binding |
+| 集成 | B2 业务集成服务 **(`bizservice`,`service.register`)** | 方法体来源：原生适配器（RESTFUL→外部 API）/ 二开扩展接口（也用 RESTFUL 指向扩展端点） | 对接接口/外部系统、或需自定义 Java 方法体 → **一律用 RESTFUL 业务集成服务**（二开接口 = 扩展模块写 REST 接口 + RESTFUL 服务指向它）；自定义协议适配器 SPI 是「新增一种协议类型」，非常规、且不在工具支持面 |
+| 在线 | form **Online JS** | 在线后端编码 | 表单脚本 → Online JS；内联后端代码 → boundary (unsupported) |
+| 数据 | M2 runtime data | model/field 定义 | 记录读写 → M2 data；结构 → model/field |
+
+## 归类 — face → capability
+
+Each face maps to a capability; **read the capability's coverage, tools,
+recipes, and boundaries from `omc-capabilities`** — that catalogue is the prose
+authority (this section is a pointer, not a second copy). Read only the section
+you need: `omc help omc-capabilities --section "<能力>"`. At call time the
+coverage manifest is authoritative and the tool gate rejects out-of-coverage
+calls.
+
+> `blocked` / `unsupported` are **native-config** verdicts. They route the
+> behavior to another code owner (`config + backend extension`), they do NOT
+> mean the requirement is undeliverable. Compiling a blocked face into "can't
+> do it, leave it manual" is a failure mode — see 选路.
+
+Full Chinese cue vocabulary lives in `omc-requirement-vocabulary.md` — reach
+for it when a cue in step 1 is not obvious from 定面表.
+
+## 选路 — path rules
+
+> 落点判据（配置 vs 二开、组合观）的唯一权威源是 `cpdocs-guide` 的「落点」；本节只列 OMC 侧的落点执行。
+
+- **Native configuration** owns structure and lifecycle: models, fields,
+  forms, list views, rule graphs, workflow templates.
+- **Online JS** owns form interaction and presentation: visibility, labels,
+  field linkage, preview. It *previews* a computed value; the saved value
+  comes from native config or a backend extension.
+- **Backend extension** is the method-BODY source when native config cannot
+  express the logic. Expose it the normal way: **write an interface (a REST
+  endpoint) in the extension package, then register a `RESTFUL` service pointing
+  at it** (`service.register`, `adapterCode:RESTFUL`, `methodConfig.url` → the
+  extension endpoint). Do NOT use `INTERNAL` / `custom_protocol` adapters — those
+  are platform-internal protocol mechanisms, not the way a 二开 interface is
+  registered, and they are outside the write face. A RESTFUL service pointing at
+  an external API is the same face.
+- **Business-rule action dual path**: a rule's action nodes use product-native
+  CRUD/query nodes (no code) **or** bind an already-released BizMethod. Surface
+  both paths; the clarification decides.
+- **Cannot express declaratively ⇒ `config + backend extension`, do not stop** —
+  the code owner is a backend extension (interface in the extension package +
+  `RESTFUL` service + BIZ_ACTION/button binding). **Do not report "blocked" and
+  leave the value unbuilt, and do not substitute an external throwaway script.**
+
+## 澄清触发 — ask only when
+
+- the business domain is unknown, or a noun in 定面表 stays ambiguous;
+- money, cumulative values, or concurrency are involved;
+- the requirement is environment-impacting (上线 / 发布 / 生产 / 释放冻结);
+- two capabilities could satisfy it and the choice changes behavior.
+
+Proceed with the convention when the detail is cosmetic (label wording,
+layout polish) or already implied by an established project pattern.
+
+## Configuration Intent
+
+```jsonc
+{
+  "domains": ["customer", "project"],
+  "capabilities": ["model", "field", "form", "businessrule", "workflow"],
+  "intent": {
+    "entities": [{ "name": "…", "fields": [{ "name": "…", "type": "…" }] }],
+    "behaviors": [{ "trigger": "create|update|delete|button|system|timed|…", "action": "…" }],
+    "integrations": [{ "kind": "native-crud|bizmethod|b2-service", "target": "…" }]
+  },
+  "implementationPath": "native | config+onlinejs | config+backend-extension",
+  "risks": ["…"],
+  "clarifications": ["…"],
+  "acceptanceScenarios": ["…"],
+  "nextStep": "discover_and_plan | clarify | boundary"
+}
+```
+
+`clarify` whenever 澄清触发 fires; `boundary` when a face is out of coverage;
+otherwise `discover_and_plan`.
+
+## 反模式
+
+- Classifying a noun before 定面 — e.g. mapping 规则 to `dataRuleType` when a
+  cross-model graph was meant.
+- Treating 对接外部系统 as a cue to develop a custom protocol adapter SPI — that
+  is a rare NEW PROTOTYPE, not integration. The normal path is a
+  business-integration service (`service.register`).
+- Routing a saved value through Online JS.
+- Inventing a capability for a blocked face. Cite the boundary instead.
+- Emitting a plan or DTO payload here — intent stays platform-independent
+  until discovery.
+
+## 接续
+
+Intent feeds, in order: `discover_environment` (fingerprint + existing
+resources) → configuration baseline → `omc-five-piece-flow`. For a face not
+yet proven, use `omc-capability-scouting`. For the concrete tool to call, use
+`omc-tool-selection`.