chore: nudge PR synchronize (CI did not pick up 746b7e40)

The ContractFinal assembly path dropped every non-declared parameter fact,
breaking the published Schema against the reviewed merge-base contract:

- merge pinned MCP parameter metadata and the reviewed in-code runtime hints
  back into contract_final parameter resolution (318 interface_type losses,
  calendar recurrence required/required_when regressions)
- restore devapp write risk to high and publish back to write/high; the
  migration silently downgraded 14 dev write tools and re-classified publish
  as destructive
- keep dev at-least-one checks as Validate hooks with the shipped wording
  instead of publishing new typed constraints; constraint publication is a
  contract change that belongs to its own reviewed PR (aitable annotations
  reverted for the same reason)
- align RunE escape hatch, BoolFlag shadowing, guard-first ConfirmFirst
  declaration, and Sheet target preflight with behavioral tests; drop the
  retired gen_schema_decls.py helper and fix corecmd naming in docs/CHANGELOG

check-authoritative-schema-compatibility vs origin/main: ok.

AGENTS.md

@@ -21,6 +21,23 @@ primary paths, aliases, and navigation. Edit it only when reviewed exposure,
 identity, primary path, or aliases change; parameter, Skill, and metadata-only
 changes must not rewrite it mechanically.
 
+## Command framework declaration
+
+- Framework definition: `docs/rfc-command-framework-convergence.md` **§5.0**
+- Today: `helpers.LeafSpec` / `shortcut.Shortcut` → `corecmd.Spec` (+ optional `Schema`) → `corecmd.New`
+- **Declare = final Schema source**: `Flags` / `Constraints` / `Safety` / `ConstParams` / `Schema` (ToolSpec groups)
+- `Safety` uses the existing `cli.SafetySpec` directly. Its `confirmation` drives the runtime gate; `effect` / `risk` / `idempotency` are published unchanged. When `Schema` is set, convert once → `RegisterRuntimeContractFinal` (map store, no JSON/deep-clone); assembly **pass-throughs** Final.
+- **Execute** = hooks (`Validate` / `Call` / `RunE` / `PostMount`) — not a second surface authority
+- Declaration path has **no reviewed parallel fields**; migration-only `runtime_gate` annotate until `Safety` is declared
+
+## flag / help / schema homology
+
+- Decision (path A — Contract/LeafSpec is CLI-surface authority **and must embed into Schema**): `docs/flag-help-schema-homology.md`
+- Hard rule: every help/Schema fact is **declared** **or** **annotated**; never inference-only (§1.1–§1.3; framework §5.0).
+- Embed path: `corecmd.New` → `dws.schema.*` annotations → Schema catalog assembly
+- MCP metadata must not create CLI flags; optional 1:1 passthrough is a gated subset only.
+- Planned gate IDs: `HOM-P*`, `HOM-S*`, `HOM-I1`, `HOM-D1` (see that doc §4).
+
 ## Agent Schema contract
 
 The Schema data flow is one way:

CHANGELOG.md

@@ -6,6 +6,28 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+### Fixed
+
+- **Unified command safety and Shortcut runtime (H0)** — Shortcut leaves now execute through `corecmd.New`, sharing the same typed Safety confirmation gate as Leaf commands. EOF / closed stdin returns `confirmation_required`, and interactive `no` returns the existing non-zero cancellation validation error instead of reporting success for an operation that did not run. Pass `--yes` or `--dry-run` to skip the prompt.
+
+## [1.0.56-beta.2] - 2026-07-30
+
+This beta adds PRs #831 and #835 on top of v1.0.56-beta.1. It separates
+Agent Product observability and IM display identity from the stable
+edition-owned PAT and routing identity, and reduces common-path Skill context
+loading without changing the public command or Runtime Schema surface.
+
+### Changed
+
+- **Agent Product identity separation** (#831) — sends `DWS_AGENT_PRODUCT` through the new `x-dws-agent-product` observability Header and uses a valid non-empty value for the IM `clawType` display label whenever `--ai-tag` is enabled. Because `--ai-tag` defaults to `true`, callers that set `DWS_AGENT_PRODUCT` change the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls preserve their existing wire shape by sending an empty IM `clawType`, while shortcut calls omit the argument. Unset or empty Product values omit the Header and preserve the active edition's IM display default.
+- **Agent Host dimension convention** (#831) — new integrations should send the runtime form (`cloud` or `desktop`) through `DWS_AGENT_HOST` and report the product separately through `DWS_AGENT_PRODUCT`. Legacy combined labels such as `qwenwork_cloud` remain syntactically valid for compatibility.
+- **Reduced common-path Skill context** (#835) — keeps the complete 97-command Chat Shortcut inventory in Runtime Catalog and leaf Schema while routing common intents through compact Skill tables and references. When an exact command path is already known, the mono Skill no longer requires eager loading of a complete product reference. The generated Skill policy now detects drift, forced full-reference loading, and context-budget regressions; the common Chat plus shared activation estimate drops from 7,301 to 4,771 `o200k_base` tokens without changing the 845-tool Schema surface.
+
+### Fixed
+
+- **Stable PAT/routing identity** (#831) — restores the CLI-emitted open-source HTTP `claw-type` and PAT `hostControl.clawType` to the edition-fixed `openClaw` value. `DWS_AGENT_PRODUCT` no longer changes those wire values, and the client continues to derive PAT, authentication, routing, and Discovery behaviour from the existing independent signals.
+- **Portable generated Skill validation** (#835) — resolves the mono Skill name by scanning upward from the generated target, keeping `--check` independent of the repository checkout path and preventing false drift failures when an ancestor directory resembles a Skill name.
+
 ## [1.0.56-beta.1] - 2026-07-30
 
 This beta starts the v1.0.56 line on top of v1.0.55 and packages PRs #817,

Formula/dingtalk-workspace-cli-beta.rb

@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCliBeta < Formula
   desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.56-beta.1"
+  version "1.0.56-beta.2"
   license "Apache-2.0"
   keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli"
 
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-darwin-arm64.tar.gz"
-      sha256 "26b696a7807f87cf9c6a24634e08008bac0501f2664a85a8355904309068d55e"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.2/dws-darwin-arm64.tar.gz"
+      sha256 "19b52b5427dbf24acfeb1da16a93e6edfd0443389a778abbbfd381ff8f656139"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-darwin-amd64.tar.gz"
-      sha256 "28daa9fa1fc8131e3567a39042d5f34efc61d5901bf7d88a67f075a4ff366be6"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.2/dws-darwin-amd64.tar.gz"
+      sha256 "621da52d04f391234d160a0522d70c1fb2e36da59102ef201a9a3a11b706b3e8"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-linux-arm64.tar.gz"
-      sha256 "5f9ead9b939d2db31354797cc7b7431f27aaca41f171d256d4d4e9269cc66d51"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.2/dws-linux-arm64.tar.gz"
+      sha256 "4ba956463f4b583c1727f58026a6bc1fb23d27537083e3bafd541a05ab15b48b"
     else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-linux-amd64.tar.gz"
-      sha256 "06b950676cefdd8e054c76af32cd9758c4c7786908d654281d9c65e7a3d575cf"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.2/dws-linux-amd64.tar.gz"
+      sha256 "a8156ec5b89355faf8c08a65d9c088f89a7b411a418fb4b488f3d472efc79670"
     end
   end
 
   resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.1/dws-skills.zip"
-    sha256 "7448ccfc8e189b3d76b3e8f11f5dedc4f5a5b53380f9059e6af4c63a38e38f28"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.56-beta.2/dws-skills.zip"
+    sha256 "92c71fdeade88b3b76a00cb74ebd3223cc4110c7ee151d36d782537613129967"
   end
 
   def install

docs/architecture.md

@@ -30,6 +30,12 @@
 - `internal/security`: endpoint allowlist and domain trust
 - `internal/safety`: runtime safety checks (confirm prompts, dry-run guards)
 - `internal/cobracmd`: shared Cobra command builders
+- `internal/corecmd`: dispatch-agnostic leaf-command base — flag registration,
+  alias/env/default value resolution, required and cross-flag constraint
+  validation, Risk write confirmation, toolArgs assembly, Runtime Schema
+  projection. Distinct from `internal/cobracmd` (generic tree helpers): it owns
+  the declarative leaf contract (`corecmd.Spec`) that the LeafSpec framework is
+  built on and that the Shortcut adapter projects into.
 - `internal/pat`: PAT (Personal Access Token) authorization flow
 - `internal/output`: response formatting (json, table, raw, pretty)
 - `internal/logging`: structured logging and argument sanitization

docs/command-domain-model.md

@@ -0,0 +1,207 @@
+# command 领域模型
+
+本文档描述 `internal/corecmd` 包的领域模型——类型、概念及其关系。
+
+## 核心模型图
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         corecmd.Spec                                  │
+│                    (一个叶子命令的完整契约)                             │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  ┌─── CLI 表面 ───┐   ┌─── 参数声明 ───────────────────────────┐   │
+│  │ Use            │   │ FlagSpec[]                              │   │
+│  │ Short          │   │  ├─ Name / Kind / Default              │   │
+│  │ Long           │   │  ├─ Required / MarkRequired            │   │
+│  │ Example        │   │  ├─ Aliases[] / EnvVar (回退链)         │   │
+│  └────────────────┘   │  ├─ Bind / Transform / OmitEmpty       │   │
+│                       │  └─ Enum / Format / SchemaDescription  │   │
+│                       │                                        │   │
+│                       │ Constraint[]                            │   │
+│                       │  ├─ at_least_one                       │   │
+│                       │  ├─ exactly_one                        │   │
+│                       │  └─ mutually_exclusive                 │   │
+│                       │                                        │   │
+│                       │ ConstParams map[string]any             │   │
+│                       └────────────────────────────────────────┘   │
+│                                                                     │
+│  ┌─── 安全模型 ──────────────────────────────────────────────────┐  │
+│  │  Safety cli.SafetySpec                                       │  │
+│  │  ├─ Effect       (read / write / destructive)                │  │
+│  │  ├─ Risk         (low / medium / high)                       │  │
+│  │  ├─ Confirmation (not_required / user_required) ──▶ 运行时门 │  │
+│  │  └─ Idempotency  (idempotent / retryable / …)                │  │
+│  │                                                               │  │
+│  │  四字段彼此独立；同一值同时供运行时与 Schema 使用              │  │
+│  │  ConfirmFirst: bool (只控制确认门顺序)                         │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌─── Schema 声明 (Agent 可见的元数据) ──────────────────────────┐  │
+│  │  SchemaDecl                                                   │  │
+│  │  ├─ Title / Description                                      │  │
+│  │  ├─ DryRunDecl     {PreviewKind, RemoteReads}                │  │
+│  │  ├─ InterfaceDecl  {Mode, Availability, Reason, Ref}         │  │
+│  │  ├─ SelectionDecl  {AgentSummary, UseWhen, AvoidWhen,        │  │
+│  │  │                  Prerequisites, Tips, Examples}            │  │
+│  │  ├─ IdentityDecl   {ProductID, CanonicalPath, Aliases, ...}  │  │
+│  │  └─ Positionals[]  {Name, Type, Required, Variadic}          │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌─── 执行体 (恰好一个) ─────────────────────────────────────────┐  │
+│  │  Invoke(Ctx, toolArgs)     ← 单步：框架装配好 args 后派发     │  │
+│  │  Orchestrate(Ctx)          ← 多步：自行组装多次调用           │  │
+│  │  RunE(cmd, args)           ← 逃生舱：完全自定义               │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+│                                                                     │
+│  ┌─── 钩子 ─────────────────────────────────────────────────────┐  │
+│  │  Validate(cmd, args)   ← 条件式业务校验（约束表达不了的）      │  │
+│  │  PostMount(cmd)        ← 挂载收尾（设置 Args 等 cobra 属性）   │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 构建与执行流
+
+```
+corecmd.Spec ──── corecmd.New() ────▶ cobra.Command ──── 用户执行 ────▶ Ctx
+                     │                    │                            │
+              构建时检查:              注册产物:                    执行上下文:
+              • validateDispatchDecl   • Flags + Aliases            • Str(name)
+              • validateSafetySpec     • Annotations (Schema)       • Int(name)
+              • validateSchemaDecl     • Long (约束 help)           • Bool(name)
+              • RegisterFlags          • RunE (管线)                • StrSlice(name)
+              • ValidateConstraintDecls                            • Changed(name)
+              • embedContractIntoSchema                            • DryRun() / Yes()
+              • AnnotateConstraints
+              • PostMount
+```
+
+## 领域概念
+
+| 概念 | 类型 | 职责 |
+|------|------|------|
+| **corecmd.Spec** | struct | 一个命令的完整契约（声明 + 执行） |
+| **FlagSpec** | struct | 一个参数的注册、回退链、绑定规则 |
+| **Constraint** | struct | 参数间的关系约束 |
+| **Safety** | cli.SafetySpec | 运行时与 Schema 共用的安全契约 |
+| **SchemaDecl** | struct | Agent 可见的完整工具规格声明 |
+| **SelectionDecl** | struct | Agent 选择该工具的语义指引 |
+| **InterfaceDecl** | struct | 工具的接口模式与可用性 |
+| **DryRunDecl** | struct | dry-run 能力声明 |
+| **IdentityDecl** | struct | 工具在注册表中的身份标识 |
+| **PositionalDecl** | struct | 有序位置参数声明 |
+| **Ctx** | struct | 执行上下文（类型安全的 flag 读取） |
+| **New** | func | 统一构建器（`corecmd.Spec` → `*cobra.Command`） |
+
+## SafetySpec
+
+`corecmd.Spec.Safety` 直接复用 `cli.SafetySpec`，没有 command 自定义 Risk/Safety 枚举，也没有 `SafetyDecl` 覆盖层：
+
+```go
+Safety: cli.SafetySpec{
+    Effect:       "write",
+    Risk:         "high",
+    Confirmation: "user_required",
+    Idempotency:  "unknown",
+}
+```
+
+- `Confirmation == "user_required"` 时执行确认；`--yes` 和 `--dry-run` 可跳过交互。
+- `Effect`、`Risk`、`Idempotency` 不参与确认决策，也不会改写 `Confirmation`。
+- 任意一个字段非空时，四个字段必须全部显式声明；构建时拒绝部分声明。
+- 完全空值仅作为历史只读默认，最终发布为 `read/low/not_required/idempotent`。
+
+## FlagSpec 有效值回退链
+
+框架统一的 flag 值解析顺序：
+
+```
+显式主 flag (Changed)
+    │ 空?
+    ▼
+隐藏别名 (Changed, 按声明序)
+    │ 空?
+    ▼
+环境变量 (EnvVar)
+    │ 空?
+    ▼
+注册默认值 (Default)
+    │ 空?
+    ▼
+ArgDefault (兜底)
+```
+
+各 Kind 的特殊行为：
+
+| Kind | 入参条件 | 回退链 |
+|------|----------|--------|
+| KindString | 有效值非空（或 !OmitEmpty） | 完整参与 |
+| KindInt | 值 ≠ 0（putInt 语义） | 完整参与 |
+| KindBool | Changed 时入参（显式 false 也下发） | 不参与别名/env 回退 |
+| KindStringSlice | 存在非空元素 | 仅 Changed 的主 flag/alias |
+
+## Constraint 约束
+
+声明式跨 flag 关系，构建时校验合法性，运行时统一执行：
+
+| Kind | 语义 | 错误文案示例 |
+|------|------|-------------|
+| `at_least_one` | 至少提供一个 | "请至少指定 --a、--b 之一" |
+| `exactly_one` | 恰好提供一个 | "请指定 --a、--b 之一" / "只能指定其一" |
+| `mutually_exclusive` | 最多提供一个 | "参数 --a、--b 互斥，只能指定其一" |
+
+"是否提供"的判定复用有效值回退链（显式主 flag → 别名 → env），注册默认值不算作已提供。
+
+## SchemaDecl 子结构
+
+### SelectionDecl（Agent 选择指引）
+
+```go
+SelectionDecl{
+    AgentSummary: "一句话描述工具做什么",
+    UseWhen:      []string{"在什么场景下应该选择这个工具"},
+    AvoidWhen:    []string{"什么场景不应该用，应该用什么替代"},
+    Prerequisites: []string{"使用前提条件"},
+    Tips:          []string{"使用技巧"},
+    Examples:      []string{"dws dev app create --name Bot --dry-run"},
+}
+```
+
+### InterfaceDecl（接口模式）
+
+```go
+InterfaceDecl{
+    Mode:         "composite",  // local / pinned / composite
+    Availability: "available",  // available / unavailable
+    Reason:       "...",        // composite/unavailable 时的原因
+    ProductID:    "...",        // pinned 时的 ref
+    RPCName:      "...",        // pinned 时的 ref
+}
+```
+
+### DryRunDecl（dry-run 能力）
+
+```go
+DryRunDecl{
+    PreviewKind: "invocation",  // invocation / request / plan
+    RemoteReads: false,         // dry-run 时是否发起远端读
+}
+```
+
+## 执行体三选一
+
+| 执行体 | 适用场景 | 框架做了什么 |
+|--------|----------|-------------|
+| **Invoke** | 单步 MCP/后端调用 | 框架完成 required→constraint→validate→buildArgs→confirm，传入装配好的 toolArgs |
+| **Orchestrate** | 多步编排 | 框架完成 required→constraint→validate→confirm，传入 Ctx 自行组装调用 |
+| **RunE** | 逃生舱 | 框架仍执行 Safety 确认，具体业务执行完全自定义 |
+
+## 设计不变量
+
+1. **一个 corecmd.Spec = 一个叶子命令的全部事实**
+2. **声明面绝不调用后端**——command 是 dispatch-agnostic
+3. **执行面绝不发明 CLI 表面**——业务 flag 必须在 Flags 声明
+4. **构建时拦截 > 运行时报错**——声明错误 panic 在注册阶段
+5. **SafetySpec 是单一事实源**——Confirmation 驱动运行时，其余字段原样进入 Schema
+6. **声明即 review**——代码中的 Schema 经 code review 后直接投影，不依赖外部 hint 文件

docs/command-framework-architecture.md

@@ -0,0 +1,270 @@
+# 命令框架架构
+
+本文档描述 `internal/corecmd` 统一命令框架的当前架构，面向框架使用者和维护者。
+
+## 概览
+
+```
+用户输入 → cobra 命令树 → corecmd.New() → 运行时管线 → 后端派发
+```
+
+命令框架将 CLI 命令的**声明**与**执行**分离：
+
+- **声明面** — 数据字段描述命令是什么（flag、约束、SafetySpec、Schema 元数据）
+- **执行面** — 钩子函数描述命令做什么（校验、派发、编排）
+
+框架负责：flag 注册、有效值回退链、required/约束校验、SafetySpec 确认、toolArgs 装配、Agent Runtime Schema 投影。
+
+## 核心类型
+
+### corecmd.Spec
+
+统一的类型化命令规格，是框架的核心数据结构：
+
+```go
+type Spec struct {
+    // 声明面
+    Use         string
+    Short       string
+    Long        string
+    Example     string
+    Flags       []FlagSpec
+    Constraints []Constraint
+    Safety      cli.SafetySpec // 运行时与 Schema 的单一安全来源
+    ConfirmFirst bool         // 确认门先于参数校验
+    ConstParams map[string]any
+    Schema      SchemaDecl    // 完整 ToolSpec 载荷
+
+    // 执行面（恰好一个）
+    Invoke      func(c *Ctx, toolArgs map[string]any) error  // 单步
+    Orchestrate func(c *Ctx) error                           // 多步
+    RunE        func(cmd *cobra.Command, args []string) error // 逃生舱
+
+    // 钩子
+    Validate    func(cmd *cobra.Command, args []string) error
+    PostMount   func(cmd *cobra.Command)
+}
+```
+
+### SafetySpec（单一安全来源）
+
+`Spec.Safety` 直接使用现有 Agent Runtime Schema 的 `cli.SafetySpec`：
+
+| 字段 | 职责 |
+|------|------|
+| `Effect` | 操作影响：read / write / destructive |
+| `Risk` | 风险等级：low / medium / high |
+| `Confirmation` | 是否需要用户确认：not_required / user_required |
+| `Idempotency` | 幂等性：idempotent / retryable / non_idempotent / unknown |
+
+四个字段彼此独立。框架只读取 `Confirmation` 决定运行时确认，其余字段原样发布到 Schema，不从一个字段机械推导另一个。非空 SafetySpec 必须一次声明完整：
+
+```go
+Safety: cli.SafetySpec{
+    Effect:       "write",
+    Risk:         "high",
+    Confirmation: "user_required",
+    Idempotency:  "unknown",
+},
+```
+
+完全空值保留历史只读默认 `read/low/not_required/idempotent`；不存在 Risk/Safety 枚举或覆盖优先级链。
+
+### FlagSpec
+
+声明一个 flag 的注册方式、有效值回退链、到 toolArgs 的绑定：
+
+```go
+type FlagSpec struct {
+    Name     string       // flag 名（kebab-case）
+    Usage    string       // --help 文案
+    Kind     FlagKind     // String / Int / Bool / StringSlice
+    Default  string       // 注册默认值
+    Required bool         // 框架校验非空
+    Aliases  []string     // 隐藏别名
+    EnvVar   string       // 环境变量回退
+    Bind     string       // toolArgs 键名（空则用 Name）
+    Transform func(string) (any, error)  // 值转换
+    // ...更多字段见源码
+}
+```
+
+### Constraint
+
+跨 flag 关系约束：
+
+```go
+type Constraint struct {
+    Kind  ConstraintKind  // at_least_one / exactly_one / mutually_exclusive
+    Flags []string
+}
+```
+
+## 有效值回退链
+
+flag 解析按以下顺序取值（先命中先生效）：
+
+```
+显式主 flag (Changed) → 隐藏别名 (Changed) → 环境变量 → 注册默认值
+                                                            │
+                                              ArgDefault ←──┘ (兜底)
+```
+
+- KindBool：仅 Changed 时生效，不参与回退链
+- KindStringSlice：仅主 flag / alias Changed 时生效，元素恒 TrimSpace
+- KindInt：非零才入 toolArgs（putInt 语义）
+
+## 构建时流程
+
+`corecmd.New(spec)` 执行以下构建时检查（失败则 panic）：
+
+1. **validateDispatchDecl** — 恰好一个执行体（Invoke/Orchestrate/RunE）
+2. **validateSafetySpec** — 非空 SafetySpec 的四个独立字段必须完整
+3. **validateSchemaDecl** — Schema 声明完整性（Description、AgentSummary、UseWhen、AvoidWhen、Examples、Interface）
+4. **RegisterFlags** — flag + alias 注册到 cobra
+5. **ValidateConstraintDecls** — 约束引用的 flag 必须存在
+6. **embedContractIntoSchema** — 投影到 dws.schema.* annotations
+7. **AnnotateConstraints** — 约束渲染到 --help
+8. **PostMount** — 调用方的挂载收尾钩子
+
+## 运行时流程
+
+生成的 `RunE` 按以下顺序执行：
+
+```
+[ConfirmFirst? → ConfirmSafety]      ← 可选：先确认后校验
+  │
+  ▼
+ValidateRequired                     ← 有效值回退链校验
+  │
+  ▼
+ValidateConstraints                  ← 互斥/至少一个/恰好一个
+  │
+  ▼
+Validate hook                        ← 条件式业务校验（可选）
+  │
+  ▼
+BuildArgs                            ← flag → toolArgs 装配
+  │
+  ▼
+ConstParams 合并
+  │
+  ▼
+[!ConfirmFirst? → ConfirmSafety]     ← 默认顺序：校验后确认
+  │
+  ▼
+Invoke(ctx, toolArgs)                ← 单步派发
+  或 Orchestrate(ctx)                ← 多步编排
+```
+
+## 消费方式
+
+### LeafSpec（MCP 直连叶子命令）
+
+```go
+func newDevAppCreateCommand(runner executor.Runner) *cobra.Command {
+    return NewLeafCommand(LeafSpec{
+        Use:     "create",
+        Short:   "创建开放平台企业内部应用",
+        Tool:    devAppCreateTool,
+        Safety: cli.SafetySpec{
+            Effect: "write", Risk: "high",
+            Confirmation: "user_required", Idempotency: "unknown",
+        },
+        ConfirmFirst: true,
+        Flags: []LeafFlag{
+            {Name: "name", Usage: "应用名称 (必填)", Bind: "name",
+             Trim: true, Required: true, RequiredHint: "--name 为必填"},
+        },
+        Schema: LeafSchema{
+            Description: "创建开放平台企业内部应用",
+            DryRun:      &LeafDryRunDecl{PreviewKind: "invocation"},
+            Interface:   &LeafInterfaceDecl{Mode: "composite", Availability: "available"},
+            Selection: LeafSelectionDecl{
+                AgentSummary: "创建钉钉开放平台应用",
+                UseWhen:      []string{"需要新建企业内部应用"},
+                AvoidWhen:    []string{"应用已存在时用 update"},
+                Examples:     []string{`dws dev app create --name "Bot" --dry-run`},
+            },
+        },
+        Call: devAppCall(runner),
+    })
+}
+```
+
+`NewLeafCommand` 经 `FromLeafSpec()` 归一为 `corecmd.Spec`，再交 `corecmd.New()` 构建。这是**完全托管模式**：声明 + 执行都归 command。
+
+### 声明元数据模式（既有命令补 Schema）
+
+执行体必须冻结时，用同一套 `LeafSpec` 词汇只声明元数据，写在命令字面量旁：
+
+```go
+baseListCmd := &cobra.Command{
+    Use: "list", Short: "获取 AI 表格列表",
+    RunE: func(cmd *cobra.Command, args []string) error { /* 原执行体不动 */ },
+}
+DeclareLeafMetadata(baseListCmd, LeafSpec{
+    Safety: aitableSafetyRead(),
+    Schema: LeafSchema{
+        Description: "列出最近访问的 AI 表格 Base。",
+        Interface:   aitableMCPInterface("list_bases"),
+        Selection: LeafSelectionDecl{
+            AgentSummary: "列出最近访问的 AI 表格 Base。",
+            UseWhen:      []string{"只需浏览最近打开过的 Base 时"},
+            AvoidWhen:    []string{"按名称查找优先 base search"},
+            Examples:     []string{"dws aitable base list"},
+        },
+    },
+})
+```
+
+`DeclareLeafMetadata` 调用 `corecmd.AttachSchema` 挂 Safety+Schema；不注册 flag、不接管参数投影。当 `Safety.Confirmation=user_required` 时，用**同一份** SafetySpec 包一层 `ConfirmSafety`，保证执行门禁与 Catalog 同源。迁移态入口；新命令仍应走 `NewLeafCommand`。
+
+### Shortcut（智能快捷方式，已接入 live mount）
+
+```go
+func mount(s Shortcut) *cobra.Command {
+    return corecmd.New(FromShortcut(s))
+}
+
+spec := FromShortcut(Shortcut{
+    Service: "chat",
+    Command: "+demo",
+    Risk:    RiskHighWrite,
+    Flags:   []Flag{...},
+    Execute: func(rt *RuntimeContext) error { ... },
+})
+```
+
+Shortcut 当前仍保留自身的 `Risk`，adapter 只在边界将它展开成完整
+`cli.SafetySpec`；command/Leaf 不再保留该枚举。Shortcut 的 Cobra
+type/default/usage provenance 保持不变，command 统一补充 Required、Enum 和关系约束投影。
+
+## 文件结构
+
+| 文件 | 职责 |
+|------|------|
+| `internal/corecmd/corecmd.go` | 核心类型 + `New` 构建器 + 运行时管线 |
+| `internal/corecmd/schema_decl.go` | SchemaDecl 载荷类型 + 声明完整性守卫 |
+| `internal/helpers/leaf.go` | LeafSpec 门面：`NewLeafCommand`（完全托管）+ `DeclareLeafMetadata`（声明元数据） |
+| `internal/shortcut/adapter.go` | FromShortcut 完整映射与 Risk 兼容边界 |
+| `internal/shortcut/runner.go` | RuntimeContext；live mount 委托 `corecmd.New(FromShortcut(s))` |
+
+## Schema 投影
+
+声明即 review：代码中的 Schema 声明经过 code review 后直接投影为：
+
+- **Agent Runtime Schema** (dws.schema.* cobra annotations)
+- **Agent Metadata** (agent-metadata JSON, 消费方为 Agent 选择器)
+- **Catalog** (catalog.json, 命令注册表)
+- **Dry-run Capabilities** (声明自动索引为 reviewed 能力)
+
+不再需要外部 hint 文件维护 selection/metadata/dry-run 信息。
+
+## 设计原则
+
+1. **声明 vs 执行分离** — Flags/Constraints/Safety/Schema 是声明；Invoke/Validate/PostMount 是执行
+2. **单一数据源** — 一份声明驱动 --help、Schema、catalog、runtime 校验
+3. **安全字段不互推** — Confirmation 单独驱动确认，Effect/Risk/Idempotency 原样发布
+4. **构建时拦截 > 运行时报错** — 声明不完整在命令注册时 panic，不等到用户触发
+5. **边界兼容** — Shortcut 暂由 adapter 转换，Leaf 直接声明 SafetySpec

docs/command-framework-comparison.md

@@ -0,0 +1,236 @@
+# 命令框架对比：DWS command vs lark-cli vs GWS
+
+本文档对比 DWS（钉钉工作区 CLI）、lark-cli（飞书 CLI）和 GWS（Google Workspace CLI / gcloud）三套命令框架的设计差异。
+
+## 总览对比
+
+| 维度 | DWS (command) | lark-cli | GWS (gcloud) |
+|------|---------------|----------|--------------|
+| 语言 | Go | Go | Python (gcloud) / Go (部分) |
+| CLI 框架 | cobra | cobra | argparse + calliope |
+| 调用底座 | MCP JSON-RPC | Lark REST SDK (`CallAPITyped`) | Google API Client |
+| 命令层次 | 2 层：LeafSpec + Shortcut | 3 层：Shortcuts + API Commands + Raw API | 2 层：surface commands + raw |
+| Schema 来源 | 代码声明投影 | 代码声明 + 运行时 introspection | API Discovery 文档自动生成 |
+| Agent 适配 | 内建 (dws.schema.*) | 内建 (--print-schema) | 外挂 (MCP adapter) |
+
+## 架构对比
+
+### DWS command
+
+```
+corecmd.Spec (声明) → corecmd.New() → cobra.Command
+     │
+     ├── cli.SafetySpec (运行时 + Schema 单一安全来源)
+     ├── FlagSpec[] (参数 + 回退链 + 绑定)
+     ├── Constraint[] (互斥/至少一个)
+     ├── SchemaDecl (Agent Selection/DryRun/Interface)
+     │
+     └── Invoke / Orchestrate / RunE (执行)
+```
+
+**核心特点**：
+- 声明与执行严格分离
+- SafetySpec 四个独立字段直接对齐 Agent Runtime Schema
+- 有效值回退链：flag → alias → env → default
+- 框架统一校验、装配、确认、投影
+- Schema 从代码声明直接投影，无外部 hint 文件
+
+### lark-cli
+
+```
+Shortcut (声明) → runner.Mount() → cobra.Command
+     │
+     ├── Risk string (确认行为)
+     ├── Scopes / ConditionalScopes (OAuth 权限)
+     ├── Flag[] (参数 + Enum + Input sources)
+     ├── AuthTypes (user/bot)
+     │
+     ├── DryRun hook → DryRunAPI
+     ├── Validate hook
+     └── Execute hook → RuntimeContext → CallAPITyped
+```
+
+**核心特点**：
+- Execute 内直接调 REST API (`CallAPITyped`)
+- DryRun 是独立 hook（返回结构化 API 计划）
+- 内建 OAuth scope 声明与预检
+- `--print-schema --flag-name` 运行时 introspection
+- 无 Schema 投影层，Agent 通过 introspection 动态发现
+
+### GWS (gcloud 风格)
+
+```
+API Discovery → 代码生成 → surface command
+     │
+     ├── arguments (从 JSON Schema 自动生成)
+     ├── request/response 映射
+     └── 自定义 action hook (少量)
+```
+
+**核心特点**：
+- Schema-first：从 API Discovery 文档自动生成命令
+- 参数直接映射 API 字段（flat schema）
+- 人工 surface command 是 thin wrapper
+- Agent 适配通过 MCP 外部 adapter
+
+## 核心设计差异
+
+### 1. 声明粒度
+
+| 能力 | DWS command | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 参数别名 + 环境变量回退 | ✅ FlagSpec.Aliases + EnvVar | ❌ 无 | ❌ 无 |
+| 声明式约束 (互斥/至少一个) | ✅ Constraint[] | ❌ 只有 Validate hook | ✅ argparse group |
+| 安全契约 | ✅ SafetySpec（effect/risk/confirmation/idempotency） | Risk | 无 |
+| Schema 投影 (Agent metadata) | ✅ SchemaDecl 内建 | ⚠️ 运行时 introspection | ❌ 外挂 |
+| 参数绑定 (flag name → API key) | ✅ FlagSpec.Bind | ❌ 手写 | ✅ 自动映射 |
+| ConstParams (固定载荷) | ✅ | ❌ 手写在 Execute | ✅ 隐式 |
+| 确认门顺序可配 (ConfirmFirst) | ✅ | ❌ 固定顺序 | ❌ 无确认机制 |
+
+### 2. 执行模型
+
+| 维度 | DWS command | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 参数装配 | 框架自动 (BuildArgs) | 手写 (`runtime.Str()/Bool()`) | 自动映射 |
+| 派发方式 | Invoke(ctx, toolArgs) | Execute(ctx, runtime) | 自动调用 |
+| 多步编排 | Orchestrate(ctx) | Execute 内链式 CallAPITyped | 不支持 |
+| DryRun | 框架统一 (--dry-run flag) | 独立 DryRun hook 返回 API 计划 | 部分命令支持 |
+| 错误分类 | apperrors 类型化 | errs.Problem 类型化 | HTTP status 映射 |
+
+### 3. Agent 适配
+
+| 维度 | DWS command | lark-cli | GWS |
+|------|-------------|----------|-----|
+| 工具发现 | `dws schema --all` (静态 catalog) | `--print-schema` (运行时) | API Discovery |
+| 选择指引 | SelectionDecl (UseWhen/AvoidWhen) | Description + Tips | 无 |
+| 安全声明 | cli.SafetySpec 直接声明 | Risk string | 无 |
+| dry-run 能力声明 | DryRunDecl (reviewed) | DryRun hook 存在性 | 无 |
+| 接口模式 | InterfaceDecl (local/pinned/composite) | 隐式 (全部 REST) | 隐式 (全部 REST) |
+
+### 4. Schema 生命周期
+
+```
+DWS:      代码声明 → code review → cobra annotation → catalog/metadata JSON
+          (单一数据源，构建时验证完整性)
+
+lark-cli: 代码声明 → 运行时 introspection → Agent 动态发现
+          (无离线 catalog，Agent 必须执行命令才能发现)
+
+GWS:      API Discovery JSON → 代码生成 → surface command
+          (Schema-first，但命令行体验受限于 API 形状)
+```
+
+## 设计哲学对比
+
+### DWS command 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| 框架装配参数 | 消除 N 个命令各写一份 toolArgs 装配 | lark-cli 每个 Execute 手动取 flag 值 |
+| SafetySpec 单一来源 | confirmation 驱动运行时，其余字段原样发布且互不推导 | lark-cli 只有 Risk 一个维度 |
+| 声明式约束 | 构建时校验合法性 + 投影到 Schema + 渲染帮助 | lark-cli 约束隐藏在 Validate 逻辑里 |
+| Schema 构建时投影 | 离线 catalog 支持 Agent 批量发现 | lark-cli 需要逐个命令 introspection |
+| 有效值回退链 | flag → alias → env 统一语义 | lark-cli 别名是独立 Flag 手动关联 |
+| ConfirmFirst | 精确建模遗留语义 | lark-cli 确认始终在 Execute 内 |
+
+### lark-cli 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| 直连 REST API | 精确控制请求/响应，可处理分页/重试 | DWS 通过 MCP 间接调用 |
+| DryRun 返回 API 计划 | Agent 可预览将要发出的真实 HTTP 请求 | DWS dry-run 只展示参数 |
+| OAuth scope 声明 | 框架预检权限，失败提前 | DWS 依赖 MCP 层鉴权 |
+| `--print-schema` introspection | 运行时发现，无需维护离线 catalog | DWS 需要 re-generate |
+| Input sources (file/@path/stdin) | 丰富的输入方式声明 | DWS 无此抽象 |
+| PrintFlagSchema | 单 flag 级别的 JSON Schema 暴露 | DWS 只在 catalog 级别 |
+
+### GWS (gcloud) 的选择
+
+| 选择 | 理由 | 对比 |
+|------|------|------|
+| API Discovery 驱动 | 一份 Schema 生成所有：SDK/CLI/文档 | DWS/lark 手写 |
+| Flat parameter 映射 | API 字段 = CLI flag，零转换 | DWS 需要 Bind 映射 |
+| 无 shortcut 层 | API 粒度即用户粒度 | DWS/lark 有精选层 |
+
+## 代码量对比
+
+| 框架 | 核心框架代码 | 单命令声明开销 | 备注 |
+|------|-------------|---------------|------|
+| DWS command | ~1400 行 (command.go + schema_decl.go) | ~20-30 行 (纯声明) | 框架重、单命令轻 |
+| lark-cli | ~800 行 (runner.go + types.go + common.go) | ~50-150 行 (声明 + Execute 逻辑) | 框架轻、单命令重 |
+| GWS gcloud | ~5000+ 行 (calliope 框架) | ~10 行 (多数自动生成) | 框架最重、单命令最轻 |
+
+## DWS 命令声明示例 vs lark-cli
+
+### DWS (command / LeafSpec)
+
+```go
+NewLeafCommand(LeafSpec{
+    Use:    "create",
+    Short:  "创建应用",
+    Tool:   "create_dev_app",
+    Safety: cli.SafetySpec{
+        Effect: "write", Risk: "high",
+        Confirmation: "user_required", Idempotency: "unknown",
+    },
+    ConfirmFirst: true,
+    Flags: []LeafFlag{
+        {Name: "name", Usage: "应用名称", Bind: "name",
+         Trim: true, Required: true, RequiredHint: "--name 为必填"},
+    },
+    Schema: LeafSchema{
+        Description: "创建开放平台企业内部应用",
+        DryRun:    &LeafDryRunDecl{PreviewKind: "invocation"},
+        Interface: &LeafInterfaceDecl{Mode: "composite", Availability: "available"},
+        Selection: LeafSelectionDecl{
+            AgentSummary: "创建钉钉开放平台应用",
+            UseWhen:      []string{"需要新建企业内部应用"},
+            AvoidWhen:    []string{"应用已存在时用 update"},
+            Examples:     []string{`dws dev app create --name "Bot" --dry-run`},
+        },
+    },
+    Call: devAppCall(runner),
+})
+```
+
+### lark-cli (Shortcut)
+
+```go
+var CalendarCreate = common.Shortcut{
+    Service:     "calendar",
+    Command:     "+create",
+    Description: "Create a new calendar event",
+    Risk:        "write",
+    Scopes:      []string{"calendar:calendar"},
+    Flags: []common.Flag{
+        {Name: "summary", Desc: "Event title", Required: true},
+        {Name: "start", Desc: "Start time (RFC3339)", Required: true},
+        {Name: "end", Desc: "End time (RFC3339)", Required: true},
+        {Name: "attendees", Type: "string_slice", Desc: "Attendee emails"},
+    },
+    DryRun: func(ctx context.Context, rt *common.RuntimeContext) *common.DryRunAPI {
+        return &common.DryRunAPI{
+            Method: "POST",
+            Path:   "/open-apis/calendar/v4/calendars/{id}/events",
+            Body:   buildEventBody(rt),
+        }
+    },
+    Execute: func(ctx context.Context, rt *common.RuntimeContext) error {
+        body := buildEventBody(rt)
+        data, err := rt.CallAPITyped("POST",
+            "/open-apis/calendar/v4/calendars/{id}/events", nil, body)
+        if err != nil { return err }
+        return rt.Output(data)
+    },
+}
+```
+
+## 适用场景总结
+
+| 场景 | 最适合 | 原因 |
+|------|--------|------|
+| MCP 后端 + Agent Schema 投影 | **DWS command** | 内建 Schema 声明、SafetySpec 契约、离线 catalog |
+| REST API 直连 + OAuth scope 管理 | **lark-cli** | CallAPITyped + scope 预检 + DryRun API 计划 |
+| API-first 大规模 surface 生成 | **GWS gcloud** | Discovery 驱动，一份 Schema 生成一切 |
+| 多步编排 (跨服务链式调用) | **lark-cli** / DWS Orchestrate | lark 的 CallAPITyped 链式 + DWS 的 Orchestrate |
+| 遗留系统迁移 (保持行为等价) | **DWS command** | ConfirmFirst + 回退链 + catalog 漂移门禁 |

docs/flag-help-schema-homology.md

@@ -0,0 +1,246 @@
+# flag / help / schema 同源
+
+- **状态**：已决策（路径 A + Contract 嵌入 Schema）
+- **相关**：[`rfc-command-framework-convergence.md`](rfc-command-framework-convergence.md)、[`schema-dynamic-endpoint-design.md`](schema-dynamic-endpoint-design.md)
+- **实现门面**：`LeafSpec` → `corecmd.Spec` → `corecmd.New`
+
+## 1. 决策
+
+采用 **路径 A：Contract / LeafSpec 为 CLI 表面权威**，并且 **Contract 必须嵌入进 Schema**。
+
+「同源」的含义是：同一份 Contract（今日经 LeafSpec / `corecmd.Spec` 表达）同时决定——且门禁能证明——
+
+1. cobra 实际注册的 flags / required / defaults；
+2. `--help` 的 Flags 与「参数约束」段；
+3. **嵌入后的** `dws schema` / Catalog（`schema_catalog` / agent metadata 生成物）中的 parameters、关系约束和 SafetySpec。
+
+嵌入机制（已落地）：
+
+```text
+corecmd.Spec
+  → RegisterFlags + embedContractIntoSchema
+  → cobra annotations:
+       dws.schema.contract=command
+       dws.schema.property / type / required  (per flag)
+       dws.schema.constraints
+  → RegisterRuntimeContractFinal(SafetySpec + SchemaDecl)
+  → Schema 组装透传 Contract Final
+  → go:embed schema_catalog / schema_agent_metadata
+```
+
+command/Leaf 不再写 `dws.schema.risk`；SafetySpec 走类型化 Final 载荷，不使用字符串枚举注解。
+
+### 1.1 硬规则：声明 = 最终数据源（Schema 透传）
+
+受管命令进入 Schema 的叶子数据由 **Contract 声明**定义最终值；框架（`corecmd.New`）做**类型转换**并注册，Schema 组装**透传**，不得：
+
+- 把声明序列化成 JSON 注解再解析；
+- 在声明体系里再挂「评审字段」并行权威；
+- 用 hints/registry 盖写已声明字段。
+
+迁移期未迁完的叶子可暂走旧组装路径；**新声明面不含 review_reason / reviewed 字段**。写命令未设 `Safety` 时，过渡期仍可用 `runtime_gate` annotate（`HOM-S2`）。
+
+**不采用**路径 B（以 `schema_mcp_metadata` 生成全部 CLI flag/help/schema）作为主权威。钉钉 MCP meta 不是飞书 OAPI：粒度与 CLI 特有语义（二选一、OmitEmpty、ConstParams、write guard）无法从裸 meta 推出；强行生成会违反「Schema 描述 CLI，不制造 CLI」。
+
+路径 B 仅允许作为 **可选的 1:1 MCP 透传叶子通道**（见 §5），不得覆盖 LeafSpec / Shortcut 主路径。
+
+对外叙事：与飞书 **分层单权威** 同构——API/透传叶可用平台事实，产品 CLI / Shortcut 用手写契约 + 执行体——而不是「全家只有平台 meta」。
+
+### 1.2 声明（declare）：写什么、写在哪、投影到哪
+
+**定义**：声明 = 在 Contract 结构体的**数据字段**上写出事实；`corecmd.New` 据此注册 cobra、渲染 help、写入 `dws.schema.*`。钩子闭包（`Validate` / `Call` / `PostMount` / `RunE`）里的逻辑**不算**声明——即使行为正确，也不能单靠钩子让 Schema/help「猜出」该事实。
+
+命令框架边界与今日/目标对应见 RFC [`rfc-command-framework-convergence.md`](rfc-command-framework-convergence.md) **§5.0**（框架上的「声明」定义）；本节给字段级表与示例。
+
+**唯一写入面**（三选一，语义相同）：
+
+| 入口 | 类型 | 归一 |
+|---|---|---|
+| Leaf 命令 | `helpers.LeafSpec` | `FromLeafSpec` → `corecmd.Spec` |
+| Shortcut | Shortcut 声明（经 `FromShortcut`） | → `corecmd.Spec` |
+| 直接基座 | `corecmd.Spec` | `corecmd.New` |
+
+今日产品 CLI 叶子以 **`LeafSpec` 为声明门面**；字段与 `corecmd.Spec` 契约面一一对应。
+
+#### 1.2.1 契约字段（算声明）
+
+| 字段 | 声明什么 | 运行时 | 嵌入 Schema / help |
+|---|---|---|---|
+| `Flags[]`（`FlagSpec` / `LeafFlag`） | 用户可见参数面：名、类型、默认、必填、usage | 注册 cobra flag；装配 toolArgs | `dws.schema.property` / `type` / `required`；`--help` Flags |
+| `Constraints[]` | 跨 flag 关系：`at_least_one` / `exactly_one` / `mutually_exclusive`；`custom` 记录钩子校验 | 通用关系由 `ValidateConstraints` 执行；`custom` 由 `Validate` 执行 | `dws.schema.constraints`；`--help`「参数约束」 |
+| `Safety`（`cli.SafetySpec`） | effect/risk/confirmation/idempotency 四个独立事实 | `confirmation=user_required` 时 `ConfirmSafety`；`--yes` / `--dry-run` 跳过 | 同一个 SafetySpec 原样进入 Contract Final（`HOM-S1`） |
+| `ConstParams` | 固定载荷（不上 flag 表） | 并入 toolArgs；不满足 Required | **不**投影为用户 parameter |
+| `Use` / `Short` / `Long` / `Example` | 命令身份文案与示例 | cobra 自身 | help；identity 仍以 registry 为准 |
+
+`FlagSpec` 子字段（声明细节）：
+
+| 子字段 | 作用 | 是否进 Schema parameters |
+|---|---|---|
+| `Name`, `Usage`, `Kind`, `Default` | 注册名/说明/类型/DefValue | 是（name/type；default 与 cobra 对齐） |
+| `Required` / `MarkRequired` | 非空校验 / cobra 硬必填 | 是（`required`） |
+| `RequiredHint`, `Aliases`, `EnvVar` | 校验提示、隐藏别名、环境回退 | 否（执行细节；别名不上主 parameter 表） |
+| `ArgDefault`, `Bind`, `OmitEmpty`, `Trim`, `Transform` | toolArgs 装配语义 | 否（载荷细节；`Bind` 可进 property 映射，但不另造 flag） |
+
+#### 1.2.2 编排 / 执行字段（不算声明）
+
+| 字段 | 角色 | 禁止用来「冒充」的声明 |
+|---|---|---|
+| `Validate` | 条件式/领域校验钩子 | 不得在此 `Flags().String(...)` 注册业务 flag；不得只靠钩子表达「必填/互斥」而不写 `Flags`/`Constraints` |
+| `Call` / `Invoke` / `Orchestrate` | 执行体 | 不得 `params[k]=…` 装配业务参数（应在 `Flags`/`ConstParams`） |
+| `PostMount` | 挂载后收尾（annotate、领域工具注入） | 不得注册业务 flag；分页等横切由领域工具注入并可走 annotate |
+| `RunE` | 逃生舱（整段手写） | 表面事实仍须 Flags 声明；框架仍按 Safety 执行确认 |
+| `Server` / `Tool` | MCP 路由 | 不构成 CLI parameter 声明 |
+
+#### 1.2.3 最小声明示例
+
+```go
+// 读：Safety 四字段显式对齐 Schema
+NewLeafCommand(LeafSpec{
+    Use: "get", Short: "…", Tool: "…",
+    Safety: cli.SafetySpec{
+        Effect: "read", Risk: "low",
+        Confirmation: "not_required", Idempotency: "idempotent",
+    },
+    Flags: []LeafFlag{
+        {Name: "unified-app-id", Usage: "…", Bind: "unifiedAppId", Trim: true, Required: true},
+    },
+    Call: devAppCall(runner), PostMount: devAppMeta(tool),
+})
+
+// 写：同一个 SafetySpec 同时驱动确认与 Schema
+NewLeafCommand(LeafSpec{
+    Use: "publish", Short: "…", Tool: "…",
+    Flags: []LeafFlag{ /* … */ },
+    Safety: cli.SafetySpec{
+        Effect: "write", Risk: "medium",
+        Confirmation: "user_required", Idempotency: "unknown",
+    },
+    Call: devAppCall(runner), PostMount: devAppMeta(tool),
+})
+
+// 迁移期旧写命令：确认走 annotate，见 §1.3 —— 不是新声明面
+NewLeafCommand(LeafSpec{
+    Use: "create", /* Flags… */,
+    Validate: func(cmd *cobra.Command, _ []string) error {
+        return devAppRequireWriteGuard(cmd, "create") // 执行守卫，不是 Contract 声明
+    },
+    Call: devAppCall(runner),
+    PostMount: devAppMetaWrite(tool), // 人工标注 runtime_gate
+})
+```
+
+**空 `Safety` 的含义**：command 为兼容旧只读叶保留 `read/low/not_required/idempotent` 默认。因此「会改状态却留空 Safety」**不是**合法声明；新 Leaf 必须写完整 SafetySpec，未迁移旧路径则按 §1.3 标注 gate。
+
+### 1.3 人工标注（annotate）：声明的补充通道
+
+当事实无法或不愿放进 Contract 字段时，必须**显式**落注解 / 评审源，禁止组装期推断：
+
+| 标注手段 | 典型值 | 何时用 |
+|---|---|---|
+| `cli.AnnotateRuntimeGate` / `devAppMetaWrite` | `dws.schema.runtime_gate=devAppRequireWriteGuard` | 尚未迁移到 SafetySpec 的旧写命令（`HOM-S2`） |
+| `cli.AnnotateRuntimeRisk` | `dws.schema.risk=…` | Shortcut 暂存的旧兼容路径；command/Leaf 禁止新增 |
+| `cli.AnnotateRuntimeFlag` / Constraints | 与 embed 同形 | 手写 cobra 叶补齐表面（长期应迁入 Contract） |
+| reviewed `schema_hints/metadata` Safety | effect/risk/confirmation | 迁移期遗留；受管命令收敛后让位于 Safety/gate |
+
+标注与声明冲突时：**Contract 声明胜**（路径 A）。标注不得发明未注册的 CLI flag。
+
+### 1.4 Schema 全覆盖（`ToolSpec` 无空洞）
+
+`dws schema` 叶子模型是 `cli.ToolSpec`。命令框架必须为**每一个字段组**指定权威；完整矩阵在 RFC **§5.0.4**，摘要：
+
+| ToolSpec 组 | 权威类 | 框架声明字段 / 其它源 |
+|---|---|---|
+| Identity | 评审源 | `schema_command_registry` |
+| Parameters.`name/type/required/default/property` | **声明**（或同形 annotate） | `Flags` / `Bind` |
+| Parameters.`description` | 声明 usage + 可选 hints overlay | `Usage`；hints 不得改 type/required/default |
+| Parameters.`interface_*` | 评审源 | MCP meta / bindings；**不造 flag** |
+| Constraints | **声明** | `Constraints` |
+| Positionals | **声明** 或显式 annotate | 目标 `Args`；禁止推断 |
+| Safety.`effect/risk/confirmation/idempotency` | **声明**完整 `Safety`，或迁移期 `runtime_gate` / reviewed Safety | 四字段独立；不得互相推导 |
+| DryRun | 评审源 | dry-run capabilities registry |
+| Interface | 评审源 | MCP + agent metadata |
+| Selection | 评审源 | `schema_hints/selection` |
+| FieldProvenance / Extensions | 组装派生或评审扩展 | 组装器；与 delivered value 一致 |
+| （非 Schema parameter）ConstParams | **声明** | 载荷；不上 parameters 表 |
+
+验收：新增 Schema 字段必须同步改 RFC §5.0.4 + 本表；受管写命令 Safety 不得无主。
+
+## 2. 字段归属（每一类恰好一个写入者）
+
+| 字段类 | 权威 | 投影到 |
+|---|---|---|
+| flags / defaults / required / enum / 关系约束 / 运行时 Risk | Contract（LeafSpec / `corecmd.Spec` 门面） | cobra、`--help`、Schema `parameters` / constraints / confirmation |
+| ConstParams、Bind、OmitEmpty、Transform | 同上（载荷声明，不上 flag 表） | toolArgs；Schema 不把 ConstParams 伪装成用户 flag |
+| canonical path / aliases / navigation / exposure | `schema_command_registry`（+ reviewed manual additions） | Schema identity |
+| use_when / avoid_when / examples / agent_summary 文案 | `schema_hints/selection` | Schema selection |
+| RPC tool 形状、`interface_ref`、interface 描述 | `schema_mcp_metadata` + `schema_parameter_bindings` | Schema `interface_*` 字段；**不得创建 flag** |
+| 参数描述 overlay（可选） | `schema_hints/metadata` 仅补充 usage 文案 | 与 Contract/cobra 冲突时 **Contract/cobra 胜** |
+| 遗留 Safety 文案（迁移期） | 今日仍可读 `schema_hints/metadata` safety | 受管命令收敛后以 Contract.Safety / runtime_gate 为准（见 §4） |
+| dry-run 正能力 | reviewed dry-run registry | Schema `dry_run` |
+| positionals | Contract Args / 显式 annotate | Schema `positionals` |
+| FieldProvenance | 组装派生 | Schema provenance（与值一致） |
+
+Identity 与 selection **刻意不**由 Contract 取代（RFC 决策 8 / schema 设计硬规则）。**完整无空洞表见 RFC §5.0.4。**
+
+## 3. 当前缺口与目标闭环
+
+已具备：
+
+- Flags / ConstParams / Constraints → 注册、校验与 `ConstraintHelp`；SafetySpec → 运行时 `ConfirmSafety`（command）；
+- Call / Execute 作为执行体；业务参数不得在 Call 内装配（helpers 门禁）；
+- **Contract → Schema 嵌入**：参数/约束写原生 annotation，SafetySpec 与 SchemaDecl 注册为类型化 Contract Final 并由 Schema 组装透传。
+
+仍缺：
+
+1. `HOM-P*` / `HOM-D1` 门禁：禁止 hints 静默改写 type/required/default；help ≡ schema parameters；
+2. 重新 `make generate-schema` 后把嵌入结果固化进签入 catalog（注意本机 OOM）；identity/selection 仍走评审源。
+
+已落地（写命令确认语义，`HOM-S2` 起点）：
+
+- `AnnotateRuntimeGate` / `dws.schema.runtime_gate`；Leaf `PostMount: devAppMetaWrite`；手写 delete/robot 等同路径显式标注；
+- Schema 组装在无 Contract Safety 但有 gate 时 overlay `confirmation=user_required`（`applyContractGateToSafety`）；
+- AST/mount 测试：新 Leaf 须声明完整 SafetySpec；尚未迁移的旧路径须有 runtime_gate。
+
+## 4. Schema 投影与 Safety 门禁规划
+
+以下门禁在落地时应作为独立 policy / 测试交付（门禁 ID 稳定，便于 CI 认领）。
+
+| Gate ID | 断言 | 范围 |
+|---|---|---|
+| `HOM-P1` | 受管 leaf 的 schema `parameters[].name` 集合 ≡ cobra 本地 flag 名集合（排除全局 persistent） | LeafSpec / 未来 Contract 编译命令 |
+| `HOM-P2` | schema parameter `type` / `required` / `default` 与 cobra DefValue / MarkFlagRequired / FlagSpec 一致；hints overlay **不得**改写这三项，只可补 description | 同上 |
+| `HOM-P3` | schema 关系约束（require_one_of / mutually_exclusive）≡ Contract/Leaf `Constraints` 投影（与 `AnnotateConstraints` 同构） | 声明了 Constraints 的命令 |
+| `HOM-S1` | 若 Contract/Leaf `Risk` ∈ {write, high-risk-write}，则 schema `confirmation=user_required`，且 help Safety 行与之同语义 | 使用 Risk 确认的受管命令 |
+| `HOM-S2` | 若命令走显式 write guard（如 `devAppRequireWriteGuard`）而非 Risk，则必须人工标注 `dws.schema.runtime_gate`（或等价 reviewed Safety）；Schema 不得呈 `confirmation=not_required`；符合 §1.1 declare OR annotate | 今日 devapp 写命令 |
+| `HOM-S3` | `Risk=read`（或空→read）不得投影为 `user_required`，除非有 reviewed exclusion reason | 受管读命令 |
+| `HOM-I1` | `interface_ref` 存在时，bindings 覆盖的 CLI flag ⊆ Contract flags；MCP meta **不**引入额外 CLI flag | 有 MCP 绑定的命令 |
+| `HOM-D1` | `dws <path> --help` Flags 段与 schema leaf parameters 零未解释增量 | 抽样 + 受管全集逐步扩大 |
+
+落地顺序建议：
+
+1. 先对 LeafSpec 命令实现 `HOM-P1`/`HOM-P2`/`HOM-P3`（反射 cobra 即可起步，因 flag 已由 Contract 注册）；
+2. 再收 `HOM-S1`–`S3`（需产品确认 devapp 是否升格 Risk，或保持 guard + 诚实 provenance）；
+3. `HOM-I1`/`HOM-D1` 接入 `check-schema-*` / PR 门禁。
+
+## 5. 路径 B 子通道：1:1 MCP 透传叶（可选，非主路径）
+
+仅当同时满足以下条件时，才允许「从 MCP meta 生成 flag/help/schema 参数」：
+
+1. CLI path ↔ 单一 MCP tool **严格 1:1**，无多步、无按名解析、无本地 effect；
+2. 无不在 MCP input schema 中的 CLI 特有 flag（含 guard 专用语义 flag 除外的全局 `--yes`/`--dry-run`）；
+3. 无 ConstParams / Transform / 跨 flag 约束 / Call 内业务逻辑；
+4. Risk/confirmation 在 meta 或并列 reviewed Safety 中有显式来源，不靠生成器猜测；
+5. 在 registry 中标记 `surface_kind=mcp_passthrough`（名称可调整），且 **不得**与 LeafSpec/Shortcut 手写定义双注册同一 `cli_path`；
+6. 文档与门禁写明：该通道是子集优化，失败时回退/禁止扩张到产品 CLI。
+
+显式排除（永远走路径 A / Shortcut）：
+
+- 全部 `LeafSpec` 命令（含 `dws dev app …`）；
+- 全部 `+shortcut` 与 smart 编排；
+- 任何需要 `devAppRequireWriteGuard`、cursor 工具注入、或响应投影的命令。
+
+## 6. 非目标
+
+- 不把 selection 文案或 canonical identity 塞进 Contract。
+- 不要求删除 LeafSpec 门面。
+- 不把「生成 catalog 字节一致」当作运行时同源的充分条件（仍需 `HOM-*` 与差分门禁）。

docs/reference.md

@@ -5,8 +5,8 @@
 | Variable | Purpose / 用途 |
 |---------|---------|
 | `DWS_CONFIG_DIR` | Override default config directory / 覆盖默认配置目录 |
-| `DWS_AGENT_PRODUCT` | Optional, caller-declared Agent product sent through the existing HTTP `claw-type` header (for example `qwenwork`). Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[A-Za-z0-9][A-Za-z0-9_-]*$`. Unset or empty values preserve the edition default (`openClaw` in the open-source build). / 可选、由调用方声明的 Agent 产品标识，经校验后覆盖 HTTP `claw-type` 请求头；未设置或为空时保持当前发行版默认值 |
-| `DWS_AGENT_HOST` | Optional, caller-declared Agent runtime form sent as `x-dws-agent-host` (for example `cloud` or `desktop`). Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[a-z0-9][a-z0-9_-]*$`; unset values are omitted. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 `x-dws-agent-host` 发送；未设置时省略 |
+| `DWS_AGENT_PRODUCT` | Optional, caller-declared Agent product sent as `x-dws-agent-product` (for example `qwenwork`) for downstream logs/BI and used as the IM `clawType` display label when `--ai-tag` is enabled. `--ai-tag` defaults to `true`, so a configured Product changes the displayed label by default. With `--ai-tag=false`, native `chat message send` / `reply` calls send an empty `clawType`, while shortcut calls omit the argument. Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[A-Za-z0-9][A-Za-z0-9_-]*$`. Unset or empty values omit the Header and use the edition's IM display default. This client never uses Product to change the separate HTTP `claw-type` PAT/routing label. / 可选、由调用方声明的 Agent 产品标识，经校验后作为 `x-dws-agent-product` 发送，并用于 IM 小尾巴；`--ai-tag` 默认为 `true`，因此配置 Product 后默认会改变展示标签。使用 `--ai-tag=false` 时，原生 `chat message send` / `reply` 发送空的 `clawType`，shortcut 调用则省略该参数。未设置时省略请求头且 IM 使用发行版默认值；本客户端不会用 Product 修改独立的 HTTP `claw-type` |
+| `DWS_AGENT_HOST` | Optional, caller-declared Agent runtime form sent as `x-dws-agent-host` (for example `cloud` or `desktop`) for downstream logs/BI. Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match `^[a-z0-9][a-z0-9_-]*$`; unset values are omitted. This client does not use Host for PAT, authentication, Discovery, or MCP endpoint selection. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 `x-dws-agent-host` 发送给下游日志/BI；本客户端不使用该值进行 PAT、鉴权、Discovery 或 MCP 端点选择，未设置时省略 |
 | `DWS_<PRODUCT>_MCP_URL` | Override a product MCP endpoint for local development / 本地开发时覆盖指定产品 MCP endpoint |
 | `DWS_CLIENT_ID` | OAuth client ID (DingTalk AppKey) |
 | `DWS_CLIENT_SECRET` | OAuth client secret (DingTalk AppSecret) |
@@ -14,23 +14,36 @@
 | `DWS_ALLOW_HTTP_ENDPOINTS` | Set `1` to allow HTTP for loopback during dev / 设为 `1` 允许回环地址 HTTP，仅用于开发调试 |
 | `DWS_DISABLE_KEYCHAIN` | macOS only. Set `1` to skip system Keychain for the encryption key and use file-based storage (same scheme as Linux). For sandboxed runtimes (e.g. Codex App) that block Keychain APIs. Weakens at-rest protection — DEK and ciphertext live in the same directory. / 仅 macOS。设为 `1` 时跳过系统 Keychain，密钥以文件形式存储（与 Linux 一致）。用于 Keychain API 被拦截的沙盒环境（如 Codex App）。代价是 DEK 与密文同目录，保护强度低于默认方案 |
 
-### Agent Product and Host trust model / Agent 产品与运行形态的信任模型
+### Agent Product, Host, and `claw-type` / Agent 产品、运行形态与 `claw-type`
 
-`DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared selection and
-observation signals. They are not credentials, attestations, or proof of the
-calling host's identity. DingTalk services may record them for logs/BI and may
-combine supported values with separately authenticated context for PAT
-compatibility, PAT identity/source derivation, or Discovery eligibility. A
-service must allowlist supported values and must never grant access, bypass
-authentication, or skip authorization solely because either Header claims a
-particular product or runtime form. They are not used to select ordinary MCP
-tool endpoints.
+`DWS_AGENT_PRODUCT` and `DWS_AGENT_HOST` are caller-declared observation
+signals. They are not credentials, attestations, or proof of the calling
+host's identity. The CLI validates and emits `x-dws-agent-product` and
+`x-dws-agent-host`, but does not use either value to derive its authentication,
+PAT mode, Discovery behaviour, or ordinary MCP endpoint selection. Downstream
+services own and must document their own contracts for these caller-declared
+Headers.
 
-`DWS_AGENT_PRODUCT` controls only the HTTP `claw-type` Header. The similarly
-named `clawType` tool argument on IM send operations is an independent
-message-display axis used for the “Send from AI” label. It remains controlled
-by the active edition's `ClawTypeValue` and `--ai-tag`; changing
-`DWS_AGENT_PRODUCT` does not change that message label.
+Service integrators should treat both Headers as untrusted input, allowlist
+expected values, and should not grant access, bypass authentication, or skip
+authorization solely because a Header claims a particular Product or Host.
+
+The HTTP `claw-type` Header is a separate, edition-fixed PAT/routing label:
+`openClaw` in the open-source build. `DWS_AGENT_PRODUCT` never changes it or
+PAT `hostControl.clawType`. On IM send/reply operations with `--ai-tag`,
+however, a valid non-empty Product value is used as the `clawType` tool
+argument so the delivered message carries the matching “Send from AI” label.
+Because `--ai-tag` defaults to `true`, this display change is enabled by
+default for callers that set Product. With `--ai-tag=false`, native
+`chat message send` / `reply` calls serialize `clawType: ""`, while shortcut
+calls omit the argument; this client does not assume downstream services treat
+an empty value and an absent key as equivalent. The display-value precedence
+when the tag is enabled is valid non-empty `DWS_AGENT_PRODUCT`, then the active
+edition's `ClawTypeValue`, then `openClaw`.
+
+Do not set arbitrary Product values that the target downstream and IM services
+have not explicitly enabled; an unknown value may be ignored or may not render
+the expected label.
 
 For QwenWork, report the dimensions separately:
 
@@ -39,16 +52,25 @@ DWS_AGENT_PRODUCT=qwenwork
 DWS_AGENT_HOST=cloud       # or desktop
 ```
 
-Do not set arbitrary product values that the target service has not explicitly
-enabled. Older combined Host labels such as `qwenwork_cloud` still satisfy the
-generic syntax for compatibility, but new integrations should use the
-two-dimensional convention above.
+Older combined Host labels such as `qwenwork_cloud` still satisfy the generic
+syntax for compatibility, but new integrations should use the two-dimensional
+convention above.
 
 `DWS_AGENT_PRODUCT` 和 `DWS_AGENT_HOST` 均由调用方声明，不是认证凭据，也不能证明
-真实宿主身份。服务端可以在独立认证上下文中将受支持值用于日志/BI、PAT 兼容策略、
-PAT 身份/来源派生或 Discovery 准入，但不得仅凭这两个 Header 放权、绕过认证或跳过
-授权。HTTP `claw-type` 与 IM 消息发送参数 `clawType` 是两个独立维度；后者仅控制
-“Send from AI”展示，仍由发行版 `ClawTypeValue` 和 `--ai-tag` 决定。
+真实宿主身份。CLI 只负责校验并发送 `x-dws-agent-product` 与 `x-dws-agent-host`，
+不会用它们派生本客户端的鉴权、PAT 模式、Discovery 行为或 MCP 端点；下游服务的
+使用契约由对应服务自行定义和说明。HTTP `claw-type` 是发行版固定的 PAT/路由标签，
+开源版固定为 `openClaw`，不受 `DWS_AGENT_PRODUCT` 影响。
+
+服务集成方应将这两个请求头视为不可信输入并对白名单值做校验，不应仅因请求头声明了
+某个 Product 或 Host 就授予访问、绕过认证或跳过鉴权。
+
+`--ai-tag` 默认为 `true`，因此配置合法非空 Product 后，默认发送的 IM 工具参数
+`clawType` 及小尾巴会随之改变。传入 `--ai-tag=false` 时，原生
+`chat message send` / `reply` 会发送 `clawType: ""`，shortcut 调用则省略该参数；
+本客户端不假定下游会将空值与键缺失等价处理。启用小尾巴时，展示值优先级依次为
+`DWS_AGENT_PRODUCT`、当前发行版的 `ClawTypeValue`、`openClaw`。不要传入目标下游及
+IM 服务未明确支持的 Product 值，否则可能被忽略或无法展示预期标签。
 
 ## Exit Codes / 退出码
 

docs/schema-dynamic-endpoint-design.md

@@ -6,12 +6,14 @@ DWS Schema 是当前二进制公开 CLI 的版本化 Agent 执行契约。它描
 
 设计遵循三条硬规则：
 
-1. **Schema 描述 CLI，不制造 CLI。** `CommandRegistry`、manual hint、metadata 和 Catalog 都不能凭空创建 Cobra 命令或 flag；registry 中的每个路径都必须精确绑定真实 runnable Cobra leaf。
+1. **Schema 描述 CLI，不制造 CLI。** `CommandRegistry`、manual hint、metadata 和 Catalog 都不能凭空创建 Cobra 命令或 flag；registry 中的每个路径都必须精确绑定真实 runnable Cobra leaf。**`schema_mcp_metadata` 同样不得生成 CLI flag**——它只提供 interface 事实（见 §4.1 同源决策）。
 2. **所有来源只解析一次。** 来源经过统一 resolver 进入 typed `SchemaRegistry`，所有查询、导出和门禁都消费同一个 `SchemaRegistry/SchemaIndex`。
 3. **Registry-first，Catalog 只出不进。** reviewed `CommandRegistry` 是稳定 command identity/navigation 的唯一事实源；`schema_catalog/`（`catalog.json` + 每产品 `tools/<product>.json`）和其他生成 JSON 只是下游发布物，不能成为命令、metadata 或下一轮 Catalog 的来源。运行时 production loader 解码 embedded snapshot 只是交付边界，不是 source resolution。
 
 Schema 不调用 MCP `tools/list`，不访问网络，也不读取用户本地 discovery cache。
 
+**flag / help / schema 参数面同源**（已决策）：Contract / LeafSpec 为 CLI 表面权威；分层字段归属与门禁 ID 见 [`flag-help-schema-homology.md`](flag-help-schema-homology.md)。
+
 ## 2. 单向数据流
 
 ```text
@@ -95,8 +97,10 @@ DWS 与 Lark 保持**架构同构**，而不是强行复制字段：
 | typed command/metadata registry | `EffectiveCommandRegistry`、`BoundCommandRegistry` 与最终 `SchemaRegistry` |
 | navigation catalog/index | 从同一 `ToolSpec` 派生的 `SchemaIndex` |
 | schema renderer/envelope | overview、product/group、leaf、`--all` projections |
+| API Commands ← 平台 OAPI meta | **不**作为 DWS 主路径；可选 1:1 MCP 透传子集见同源文档 §5 |
+| Shortcuts ← 手写声明 + Execute | LeafSpec / Shortcut + Contract 表面（路径 A） |
 
-共同点是：强类型 registry 持有已审核、已绑定、已解析的事实，index 只负责确定性导航，renderer 只投影，不重新读取来源或做 precedence。DWS 的 base Registry 与 reviewed manual command additions 在绑定前合并为唯一的 `EffectiveCommandRegistry`，因此不存在 “native-first”、“legacy registry fallback” 或 Catalog fallback。
+共同点是：强类型 registry 持有已审核、已绑定、已解析的事实，index 只负责确定性导航，renderer 只投影，不重新读取来源或做 precedence。DWS 的 base Registry 与 reviewed manual command additions 在绑定前合并为唯一的 `EffectiveCommandRegistry`，因此不存在 “native-first”、“legacy registry fallback” 或 Catalog fallback。飞书也是**分层单权威**（API 用平台 meta，Shortcut 用手写契约），不是全家只有 meta——DWS 对齐的是这一分层，而不是「用 MCP meta 生成全部 CLI」。
 
 DWS 内部 resolved model 为：
 
@@ -121,20 +125,33 @@ DWS 当前对外仍保留兼容 wire：leaf 使用 flat `parameters`，安全和
 
 | 来源 | 负责内容 | 明确不负责 |
 |---|---|---|
+| Contract / LeafSpec / `corecmd.Spec` | **CLI 表面权威**：flags、defaults、required、enum、关系约束、运行时 Risk；编译为 cobra 与 help | canonical identity、selection 文案、虚构 RPC |
 | `schema_command_registry.json` | reviewed `CommandRegistry`：稳定 canonical identity、primary CLI path、alias、exposure 和导航 | 创建 Cobra 命令/flag、参数、安全、endpoint/token |
 | reviewed manual command additions | 将一个精确存在的 runnable Cobra leaf 合并进 `EffectiveCommandRegistry`；必须 reviewed 且带 reason | 运行时 fallback、覆盖冲突 identity、创建命令 |
-| Go/Cobra | 路径是否真实可执行、Cobra 接受的 flag、CLI 类型/默认值、执行校验、help 文本 | 稳定 canonical identity、Agent 场景选择、虚构 RPC |
+| Go/Cobra | Contract 编译后的可执行投影：路径是否真实可执行、Cobra 接受的 flag、DefValue、help 文本 | 稳定 canonical identity、Agent 场景选择、虚构 RPC；**不得**成为与 Contract 平行的第二套 flag 权威 |
 | native Schema identity annotations | implementation-side consistency evidence；存在时必须与 `EffectiveCommandRegistry` 精确一致 | 提供、补全、推断或覆盖 identity |
-| `schema_hints/metadata/*.json` parameter overlays | 精确覆盖现有 flag 的描述、映射、类型和 required 语义；并承载 safety / `runtime_gate` / interface | 创建命令/flag、绕过 completeness、虚构 RPC |
-| typed parameter metadata / constraints | `required_when`、one-of、互斥、联动、格式、枚举、位置参数 | 命令 identity |
-| `schema_parameter_bindings.json` | 稳定 CLI flag 到 RPC property 的映射 | 命令发现、risk 推断 |
-| `schema_mcp_metadata.json` | pinned RPC identity、接口描述和脱敏参数事实 | CLI identity、运行时路由、risk 推断 |
+| `schema_hints/metadata/*.json` parameter overlays | 补充 flag **description** 等文案；迁移期可读 safety | 创建命令/flag；**不得**静默改写 type/required/default（与 Contract 冲突时 Contract/cobra 胜）；不得绕过 completeness、虚构 RPC |
+| typed parameter metadata / constraints | 由 Contract 约束投影而来的 `require_one_of` / 互斥等；以及仍需 reviewed 的 `required_when` 等 | 命令 identity |
+| `schema_parameter_bindings.json` | 稳定 CLI flag 到 RPC property 的映射 | 命令发现、risk 推断、创建 CLI flag |
+| `schema_mcp_metadata.json` | pinned RPC identity、接口描述和脱敏参数事实（interface 同源） | CLI identity、运行时路由、**创建 CLI flag**、risk 推断 |
 | `schema_hints/selection/*.json` | reviewed selection prose（summary / use_when / avoid_when / examples） | 创建 Cobra 命令或参数、改写 safety |
 | Skills/Markdown | 产品路由、工作流和使用建议 | 命令存在性和 flag 事实 |
 | `schema_catalog/`（catalog.json + tools/<product>.json）及其他 generated JSON | resolved registry 的兼容发布序列化；运行时由 production loader 解回 typed registry/index | generation/source resolution 输入、identity fallback、手工修复源 |
 
 `schema_command_registry.json` 承载 reviewed `CommandRegistry`。Manual command addition 先以确定性规则合并进 effective registry；从 binder 开始，下游只看到一个稳定 identity/navigation 模型。旧 wire 中的 `surface_hash` / `surface_tools` 字段仅为兼容名称，语义已经是 effective Registry hash/coverage，不构成第二事实源。
 
+### 4.1 flag / help / schema 同源（路径 A + 嵌入）
+
+完整决策、字段归属表、`HOM-*` 门禁规划与可选 MCP 透传准入条件见 [`flag-help-schema-homology.md`](flag-help-schema-homology.md)。
+
+摘要：
+
+- **同源面**：Contract → cobra flags ≡ `--help` Flags ≡ **嵌入注解后的** schema `parameters` / 关系约束；显式 `Risk` 经 `dws.schema.risk` overlay 进 Schema Safety。
+- **嵌入点**：`command.embedContractIntoSchema` 写入 `dws.schema.contract` / property / type / required；`AnnotateConstraints` 写入 constraints；Schema 组装（`runtimeToolSpecFromMetadata`）消费这些注解并进入 `go:embed` catalog。
+- **硬规则**：CLI 表面事实 = **声明（Contract 数据字段）OR 人工标注**；禁止纯推断。非 CLI 表面字段（identity / selection / interface）必须有**评审源**。声明写法见同源文档 §1.2；标注见 §1.3；**`ToolSpec` 全字段权威见 RFC §5.0.4 / 同源 §1.4**。
+- **非同源面（有意）**：identity（registry）、selection 文案（hints/selection）、RPC 形状（MCP meta 仅 `interface_*`）、dry-run 正能力 registry。
+- **禁止**：以 MCP meta 为主通道生成 Leaf/Shortcut 的 flag；hints overlay 改写 type/required/default；Schema 字段无权威归属。
+
 ## 5. 统一解析与 precedence
 
 ### 5.1 Identity
@@ -158,7 +175,7 @@ CI 同时禁止重新加入 generated native contracts 或 materialization 入
 
 `schema_command_registry.json` 是 reviewed source，不是生成快照。它必须保留
 `$schema: ./schema_command_registry.schema.json`。该 JSON Schema 对 root、product
-和 CommandSpec 全部使用 `additionalProperties: false`，并约束：
+和 corecmd.Spec 全部使用 `additionalProperties: false`，并约束：
 
 - canonical identity、`source_product_id` 和精确 CLI path 的格式；
 - `aliases` 唯一且不能复用 primary path；
@@ -291,6 +308,7 @@ dws schema --all                               # 所有工具的完整 leaf 导
 - 每个 MCP `interface_ref` 必须在 pinned interface registry 精确存在；local/composite/unavailable 必须满足同一 conflict matrix。
 - `--all` 的 tool set 必须与最终 index 一对一，且每个工具包含完整参数契约。
 - 连续两次生成必须字节稳定，提交的生成物不得漂移。
+- **同源门禁（规划，见同源文档 §4）**：受管命令逐步满足 `HOM-P1`–`P3`（parameters ≡ cobra/Contract）、`HOM-S1`–`S3`（Safety/Risk 对齐）、`HOM-I1`（interface 不创建 flag）、`HOM-D1`（help ≡ schema parameters）。hints 不得作为 type/required/default 的 winner。
 
 推荐本地验证：
 
@@ -306,8 +324,11 @@ go test ./internal/cli ./internal/app ./internal/generator/... -count=1
 
 - 运行时调用 MCP `tools/list` 或访问网络生成 Schema。
 - 从 `schema_catalog/` 等生成 JSON 反向创建/补齐 Cobra leaf、flag、CommandRegistry 或下一轮 Catalog。
+- 从 `schema_mcp_metadata` **生成或补齐** LeafSpec/Shortcut 主路径的 CLI flag（interface overlay 除外）；未满足同源文档 §5 准入条件时启用「MCP 透传生成通道」。
 - 把 native annotation、legacy registry 或 Catalog 当作 identity fallback；或在 `EffectiveCommandRegistry` 之后再次选择 identity winner。
 - renderer、query 或 gate 在 `SchemaRegistry` 之后重新读取 source 并做第二次 merge。
 - 用 prefix/wildcard exclusion 隐藏未来命令。
 - 让 manual hint、CommandRegistry 或 interface metadata 宣称一个不存在的命令、flag 或 RPC 可用。
+- 让 `schema_hints/metadata` overlay 在与 Contract/cobra 冲突时赢得 type/required/default。
 - 把 `schema --all` 当作普通业务数据查询，或把其完整结果无条件注入 Agent 上下文。
+- 将 LeafSpec、`+shortcut` 或 write-guard/cursor/多步命令注册为 `mcp_passthrough` 表面。

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.0
 	github.com/itchyny/gojq v0.12.18
+	github.com/mattn/go-isatty v0.0.20
 	github.com/muesli/termenv v0.16.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad
 	github.com/spf13/cobra v1.10.2
@@ -40,7 +41,6 @@ require (
 	github.com/itchyny/timefmt-go v0.1.7 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.19 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect

internal/app/agent_host.go

@@ -33,7 +33,7 @@ func init() {
 	configmeta.Register(configmeta.ConfigItem{
 		Name:        envDWSAgentHost,
 		Category:    configmeta.CategoryExternal,
-		Description: "调用 DWS 的 Agent 运行形态标识；服务端可结合产品用于观测和 PAT 兼容策略",
+		Description: "调用 DWS 的 Agent 运行形态标识；作为 x-dws-agent-host 发送供下游观测，本客户端不使用该值改变 PAT、鉴权或路由",
 		Example:     "cloud",
 	})
 }

internal/app/agent_product.go

@@ -24,8 +24,8 @@ func init() {
 	configmeta.Register(configmeta.ConfigItem{
 		Name:         agentproduct.EnvName,
 		Category:     configmeta.CategoryExternal,
-		Description:  "调用方声明的 Agent 产品标识；覆盖 HTTP claw-type，但不是认证凭据",
-		DefaultValue: "由当前发行版决定",
+		Description:  "调用方声明的 Agent 产品标识；作为 x-dws-agent-product 发送并用于 IM 小尾巴，本客户端不使用该值改变 HTTP claw-type/PAT",
+		DefaultValue: "未设置（请求头省略，IM 使用当前发行版默认值）",
 		Example:      "qwenwork",
 	})
 }
@@ -47,25 +47,26 @@ func invalidAgentProductError() error {
 	)
 }
 
-// resolveEffectiveAgentProduct resolves the request-header identity with one
-// shared precedence rule: a valid non-empty runtime override wins, otherwise
-// the edition's MergeHeaders value wins, otherwise the OSS default is used.
-// Invalid runtime input falls back here for library callers that bypass root
-// validation; normal CLI execution rejects it before network access.
-func resolveEffectiveAgentProduct(headers map[string]string) string {
-	fallback := edition.DefaultOSSClawType
-	if value := headers[agentproduct.HeaderName]; value != "" {
-		fallback = value
+// resolveEditionClawType resolves the fixed routing/PAT identity supplied by
+// the active edition. DWS_AGENT_PRODUCT is deliberately not consulted.
+func resolveEditionClawType(headers map[string]string) string {
+	if value := headers["claw-type"]; value != "" {
+		return value
 	}
-	value, err := agentproduct.ResolveFromEnv(fallback)
-	if err != nil {
-		return fallback
-	}
-	return value
+	return edition.DefaultOSSClawType
 }
 
-func applyAgentProductOverride(headers map[string]string) map[string]string {
-	value := resolveEffectiveAgentProduct(headers)
+// applyAgentProductHeader injects only a valid, non-empty caller-declared
+// product. Invalid values are omitted on library paths that bypass root
+// validation; normal CLI execution rejects them before network access.
+func applyAgentProductHeader(headers map[string]string) map[string]string {
+	value, err := agentproduct.ResolveFromEnv("")
+	if err != nil || value == "" {
+		if headers != nil {
+			delete(headers, agentproduct.HeaderName)
+		}
+		return headers
+	}
 	if headers == nil {
 		headers = make(map[string]string)
 	}

internal/app/agent_product_test.go

@@ -26,13 +26,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func TestUnsetAgentProductKeepsOpenSourceDefault(t *testing.T) {
+func TestUnsetAgentProductOmitsHeaderAndKeepsOpenSourceClawType(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "")
 
 	headers := resolveIdentityHeaders()
-	if got := headers[agentproduct.HeaderName]; got != edition.DefaultOSSClawType {
-		t.Fatalf("%s = %q, want %q", agentproduct.HeaderName, got, edition.DefaultOSSClawType)
+	if got := headers["claw-type"]; got != edition.DefaultOSSClawType {
+		t.Fatalf("claw-type = %q, want %q", got, edition.DefaultOSSClawType)
+	}
+	if _, ok := headers[agentproduct.HeaderName]; ok {
+		t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
 	}
 }
 
@@ -59,38 +62,46 @@ func TestParseAgentProductReturnsStableValidationError(t *testing.T) {
 	}
 }
 
-func TestResolveIdentityHeadersAgentProductPrecedence(t *testing.T) {
+func TestResolveIdentityHeadersSeparatesAgentProductFromClawType(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
+			headers[agentproduct.HeaderName] = "merge-product-must-not-win"
 			headers["x-edition-header"] = "preserved"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "enterprise-default"
+			headers["claw-type"] = "credential-must-not-win"
+			headers[agentproduct.HeaderName] = "credential-product-must-not-win"
 			headers["x-enterprise-header"] = "preserved"
 			return headers
 		},
 	})
 
-	t.Run("unset keeps edition default", func(t *testing.T) {
+	t.Run("unset omits Product and keeps edition claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, "")
 		headers := resolveIdentityHeaders()
-		if got := headers[agentproduct.HeaderName]; got != "wukong" {
-			t.Fatalf("%s = %q, want wukong", agentproduct.HeaderName, got)
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
+		if _, ok := headers[agentproduct.HeaderName]; ok {
+			t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
 		}
 	})
 
-	t.Run("valid override is final", func(t *testing.T) {
+	t.Run("valid Product is final without changing claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, " qwenwork ")
 		headers := resolveIdentityHeaders()
 		if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 			t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
 		}
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
 		if got := headers["x-edition-header"]; got != "preserved" {
 			t.Fatalf("edition header = %q, want preserved", got)
 		}
@@ -102,21 +113,48 @@ func TestResolveIdentityHeadersAgentProductPrecedence(t *testing.T) {
 		}
 	})
 
-	t.Run("invalid library input falls back to edition", func(t *testing.T) {
+	t.Run("invalid library input omits Product and keeps edition claw-type", func(t *testing.T) {
 		t.Setenv(agentproduct.EnvName, "qwen work")
 		headers := resolveIdentityHeaders()
-		if got := headers[agentproduct.HeaderName]; got != "wukong" {
-			t.Fatalf("%s = %q, want wukong", agentproduct.HeaderName, got)
+		if got := headers["claw-type"]; got != "wukong" {
+			t.Fatalf("claw-type = %q, want wukong", got)
+		}
+		if _, ok := headers[agentproduct.HeaderName]; ok {
+			t.Fatalf("invalid Product must omit %s", agentproduct.HeaderName)
 		}
 	})
 }
 
-func TestApplyAgentProductOverrideAllocatesHeaders(t *testing.T) {
-	t.Setenv(agentproduct.EnvName, "qwenwork")
+func TestApplyAgentProductHeader(t *testing.T) {
+	t.Run("valid value allocates headers", func(t *testing.T) {
+		t.Setenv(agentproduct.EnvName, "qwenwork")
 
-	headers := applyAgentProductOverride(nil)
-	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
-		t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
+		headers := applyAgentProductHeader(nil)
+		if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
+			t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
+		}
+	})
+
+	for _, tc := range []struct {
+		name  string
+		value string
+	}{
+		{name: "empty value", value: ""},
+		{name: "invalid value", value: "qwen work"},
+	} {
+		t.Run(tc.name+" removes inherited header", func(t *testing.T) {
+			t.Setenv(agentproduct.EnvName, tc.value)
+			headers := applyAgentProductHeader(map[string]string{
+				agentproduct.HeaderName: "must-not-leak",
+				"x-preserved":           "yes",
+			})
+			if _, ok := headers[agentproduct.HeaderName]; ok {
+				t.Fatalf("%s must be omitted", agentproduct.HeaderName)
+			}
+			if got := headers["x-preserved"]; got != "yes" {
+				t.Fatalf("x-preserved = %q, want yes", got)
+			}
+		})
 	}
 }
 
@@ -167,17 +205,17 @@ func TestEffectiveClawTypeDoesNotInvokeEnterpriseCredentialHeaders(t *testing.T)
 	hookCalled := false
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(headers map[string]string) map[string]string {
 			hookCalled = true
-			headers[agentproduct.HeaderName] = "enterprise-default"
+			headers["claw-type"] = "enterprise-default"
 			return headers
 		},
 	})
 
-	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(agentproduct.EnvName, "qwenwork")
 	if got := effectiveClawType(); got != "wukong" {
 		t.Fatalf("effectiveClawType() = %q, want wukong", got)
 	}
@@ -186,7 +224,7 @@ func TestEffectiveClawTypeDoesNotInvokeEnterpriseCredentialHeaders(t *testing.T)
 	}
 }
 
-func TestAgentProductHeaderIsSeparateFromMessageClawType(t *testing.T) {
+func TestAgentProductControlsObservabilityHeaderAndMessageClawTypeOnly(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "qwenwork")
 
@@ -195,20 +233,24 @@ func TestAgentProductHeaderIsSeparateFromMessageClawType(t *testing.T) {
 	edition.Override(&edition.Hooks{
 		ClawTypeValue: "message-brand",
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 	})
 
-	if got := resolveIdentityHeaders()[agentproduct.HeaderName]; got != "qwenwork" {
+	headers := resolveIdentityHeaders()
+	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 		t.Fatalf("HTTP %s = %q, want qwenwork", agentproduct.HeaderName, got)
 	}
-	if got := edition.ClawType(); got != "message-brand" {
-		t.Fatalf("message clawType = %q, want message-brand", got)
+	if got := headers["claw-type"]; got != "wukong" {
+		t.Fatalf("HTTP claw-type = %q, want wukong", got)
+	}
+	if got := edition.ClawType(); got != "qwenwork" {
+		t.Fatalf("message clawType = %q, want qwenwork", got)
 	}
 }
 
-func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *testing.T) {
+func TestResolveIdentityHeadersRestoresIdentityAfterNilCredentialHeaders(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
 	t.Setenv(agentproduct.EnvName, "qwenwork")
 
@@ -218,7 +260,7 @@ func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *
 	credentialHookCalled := false
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 		EnterpriseCredentialHeaders: func(map[string]string) map[string]string {
@@ -234,25 +276,49 @@ func TestResolveIdentityHeadersRestoresAgentProductAfterNilCredentialHeaders(t *
 	if got := headers[agentproduct.HeaderName]; got != "qwenwork" {
 		t.Fatalf("%s = %q, want qwenwork", agentproduct.HeaderName, got)
 	}
+	if got := headers["claw-type"]; got != "wukong" {
+		t.Fatalf("claw-type = %q, want wukong", got)
+	}
 }
 
-func TestEffectiveClawTypeUsesAgentProductOverride(t *testing.T) {
+func TestResolveIdentityHeadersRestoresDefaultsAfterNilMergeHeaders(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	t.Setenv(agentproduct.EnvName, "")
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	edition.Override(&edition.Hooks{
+		MergeHeaders: func(map[string]string) map[string]string {
+			return nil
+		},
+	})
+
+	headers := resolveIdentityHeaders()
+	if got := headers["claw-type"]; got != edition.DefaultOSSClawType {
+		t.Fatalf("claw-type = %q, want %q", got, edition.DefaultOSSClawType)
+	}
+	if _, ok := headers[agentproduct.HeaderName]; ok {
+		t.Fatalf("unset Product must omit %s", agentproduct.HeaderName)
+	}
+}
+
+func TestEffectiveClawTypeIgnoresAgentProduct(t *testing.T) {
 	oldEdition := edition.Get()
 	t.Cleanup(func() { edition.Override(oldEdition) })
 	edition.Override(&edition.Hooks{
 		MergeHeaders: func(headers map[string]string) map[string]string {
-			headers[agentproduct.HeaderName] = "wukong"
+			headers["claw-type"] = "wukong"
 			return headers
 		},
 	})
 
 	t.Setenv(agentproduct.EnvName, "qwenwork")
-	if got := effectiveClawType(); got != "qwenwork" {
-		t.Fatalf("effectiveClawType() = %q, want qwenwork", got)
+	if got := effectiveClawType(); got != "wukong" {
+		t.Fatalf("effectiveClawType() = %q, want wukong", got)
 	}
 	t.Setenv(authpkg.AgentCodeEnv, "agent-code")
-	if got := apperrors.HostControlBlock()["clawType"]; got != "qwenwork" {
-		t.Fatalf("hostControl.clawType = %q, want qwenwork", got)
+	if got := apperrors.HostControlBlock()["clawType"]; got != "wukong" {
+		t.Fatalf("hostControl.clawType = %q, want wukong", got)
 	}
 
 	t.Setenv(agentproduct.EnvName, "")

internal/app/audit_command.go

@@ -6,6 +6,8 @@ import (
 	"encoding/csv"
 	"encoding/json"
 	"fmt"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"os"
 	"path/filepath"
 	"strconv"
@@ -64,6 +66,31 @@ func newAuditTailCommand() *cobra.Command {
 		},
 	}
 	cmd.Flags().IntVarP(&n, "lines", "n", 20, "显示最近 N 条记录")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "查看本地操作审计日志最近 N 条记录",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "local", Availability: "available",
+				Reason: "命令读取本地审计日志尾部，不绑定 pinned MCP RPC",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "查看本地操作审计日志最近 N 条记录",
+				UseWhen:      []string{"需要快速查看最近写入的审计记录（默认最近 20 条）"},
+				AvoidWhen: []string{
+					"需要按日期范围整段导出用 audit export",
+					"需要校验哈希链用 audit verify",
+				},
+				Examples: []string{
+					"dws audit tail",
+					"dws audit tail --lines 50",
+				},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -99,6 +126,31 @@ func newAuditExportCommand() *cobra.Command {
 	cmd.Flags().StringVar(&since, "since", "", "起始日期 (YYYY-MM-DD)")
 	cmd.Flags().StringVar(&until, "until", "", "截止日期 (YYYY-MM-DD)")
 	cmd.Flags().StringVar(&format, "format", "jsonl", "输出格式: jsonl 或 csv")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "按日期范围导出本地操作审计日志（jsonl 或 csv）",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "local", Availability: "available",
+				Reason: "命令读取并导出本地审计日志文件，不绑定 pinned MCP RPC",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "按日期范围导出本地操作审计日志（jsonl 或 csv）",
+				UseWhen:      []string{"需要把本地审计日志导出为 jsonl/csv，或按 --since/--until 取一段时间"},
+				AvoidWhen: []string{
+					"只看最近几条用 audit tail",
+					"只校验哈希链完整性用 audit verify",
+				},
+				Examples: []string{
+					"dws audit export --format jsonl",
+					"dws audit export --since 2026-07-01 --until 2026-07-14 --format csv",
+				},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -152,6 +204,28 @@ func newAuditVerifyCommand() *cobra.Command {
 		},
 	}
 	cmd.Flags().StringVar(&file, "file", "", "指定审计文件路径（默认最新文件）")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "校验本地审计日志文件的哈希链完整性",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "local", Availability: "available",
+				Reason: "命令校验本地审计日志哈希链，不绑定 pinned MCP RPC",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "校验本地审计日志文件的哈希链完整性",
+				UseWhen:      []string{"怀疑审计文件被篡改，或需要确认最新/指定文件哈希链是否完整"},
+				AvoidWhen:    []string{"只浏览或导出日志内容时用 audit tail / audit export"},
+				Examples: []string{
+					"dws audit verify",
+					"dws audit verify --file /path/to/audit.jsonl",
+				},
+			},
+		},
+	})
 	return cmd
 }
 

internal/app/event_command.go

@@ -18,6 +18,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"io"
 	"log/slog"
 	"os"
@@ -31,7 +32,6 @@ import (
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
@@ -361,6 +361,38 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 		Variadic:    true,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "non_idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "订阅并持续消费一个或多个兼容的个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "composite", Availability: "available",
+				Reason: "Reviewed composite workflow: the command creates or reuses a remote personal-event subscription and coordinates the local event bus and Stream consumer; no single pinned RPC represents the workflow.",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "订阅并持续消费一个或多个兼容的个人事件；Agent 使用 --flatten 输出顶层业务 NDJSON",
+				UseWhen: []string{
+					"需要实时监听 @我、指定单聊、指定群或指定发送人的后续消息事件",
+					"用户明确要求监听当前身份的所有单聊或所有群消息",
+					"需要监听指定单聊或群聊中的消息已读、撤回或表情回应事件",
+					"需要监听指定群的标题变更、成员进退群或群解散事件",
+					"监听机器人、外部联系人等以 openDingtalkId 标识的单聊目标",
+					"同一目标、同一过滤条件需要同时监听多个兼容事件",
+				},
+				AvoidWhen: []string{
+					"只查历史聊天记录时用 chat 查询命令",
+					"只看事件目录/字段时用 event list / event schema",
+				},
+				Examples: []string{
+					"dws event consume user_im_message_receive_user --open-dingtalk-id open-example --flatten --max-events 1 --format ndjson",
+					"dws event consume user_im_message_receive_o2o user_im_message_read_o2o --user test-user-001 --flatten --max-events 2 --format ndjson",
+				},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -728,6 +760,28 @@ func newEventListCommand() *cobra.Command {
 	cmd.Flags().BoolVar(&enabledOnly, "enabled-only", false, "个人事件目录只显示 enabled")
 	cmd.Flags().BoolVar(&includePending, "include-pending", false, "个人事件目录包含 pending 项")
 	hideEventInternalFlags(cmd, "as", "all", "all-editions", "client-id")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "列出支持的个人事件目录与状态说明",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "local", Availability: "available",
+				Reason: "命令读取 CLI 内置的个人事件目录，不绑定 pinned MCP RPC",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "列出支持的个人事件目录与状态说明",
+				UseWhen:      []string{"尚不知道可用 event_key，需要先盘点个人事件目录"},
+				AvoidWhen: []string{
+					"已知 event_key 要看 payload 字段时用 event schema",
+					"要开始监听时用 event consume",
+				},
+				Examples: []string{"dws event list --format json"},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -796,6 +850,25 @@ func newEventStatusCommand() *cobra.Command {
 	cmd.Flags().StringVar(&personalOpts.StreamSourceID, "stream-source-id", strings.TrimSpace(os.Getenv("DWS_STREAM_SOURCE_ID")),
 		"个人事件 sourceId；开源版默认 open，可由 edition 覆盖")
 	hideEventInternalFlags(cmd, "as", "all", "all-editions", "client-id", "fail-on-orphan")
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "查看个人事件订阅、本地 bus 与消费进程状态",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "composite", Availability: "available",
+				Reason: "Reviewed composite workflow: the command reads the remote personal-event subscription control plane and combines it with local bus and consumer state; no single pinned RPC represents the result.",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "查看个人事件订阅、本地 bus 与消费进程状态",
+				UseWhen:      []string{"需要确认订阅是否活跃、bus/consume 是否仍在运行"},
+				AvoidWhen:    []string{"取消订阅用 event stop；列事件目录用 event list"},
+				Examples:     []string{"dws event status --format json"},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -1037,39 +1110,22 @@ func newEventStopCommand() *cobra.Command {
 		Args:              cobra.MaximumNArgs(1),
 		DisableAutoGenTag: true,
 		RunE: func(c *cobra.Command, args []string) error {
+			// Local validation runs in DeclareLeafMetadata Validate (PreRunE)
+			// before ConfirmSafety. Confirmation is the framework wrap.
 			as, err := eventNormalizeAs(asIdentity)
 			if err != nil {
 				return err
 			}
 			if as == "user" {
 				opts.SubscribeID = firstArg(args)
-				hasSubscribeID := strings.TrimSpace(opts.SubscribeID) != ""
-				if hasSubscribeID && opts.All {
-					return fmt.Errorf("event stop --as user: subscribe_id and --all are mutually exclusive")
-				}
-				if !hasSubscribeID && !opts.All {
-					return fmt.Errorf("event stop --as user: subscribe_id is required unless --all is set")
-				}
 				if eventStopDryRun(c) {
 					return writeEventStopDryRun(c, as, opts)
 				}
-				if !eventStopConfirmed(c) {
-					return eventStopConfirmationRequired("event stop 会取消个人事件订阅并停止本地消费")
-				}
 				return eventRunPersonalStop(c, opts)
 			}
-			if err := rejectChangedFlags(c, "user", "all", "personal-event-base-url", "stream-source-id"); err != nil {
-				return fmt.Errorf("event stop: %w", err)
-			}
-			if len(args) > 0 {
-				return fmt.Errorf("event stop: subscribe_id is only supported with --as user")
-			}
 			if eventStopDryRun(c) {
 				return writeEventStopDryRun(c, as, opts)
 			}
-			if !eventStopConfirmed(c) {
-				return eventStopConfirmationRequired("event stop 会停止事件消费")
-			}
 			configDir := defaultConfigDir()
 			clientID, _, _, _, err := eventResolveAppCredentials(configDir)
 			if err != nil {
@@ -1102,6 +1158,53 @@ func newEventStopCommand() *cobra.Command {
 		Required:    false,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "destructive", Risk: "high",
+			Confirmation: "user_required", Idempotency: "unknown",
+		},
+		Validate: func(c *cobra.Command, args []string) error {
+			as, err := eventNormalizeAs(asIdentity)
+			if err != nil {
+				return err
+			}
+			if as == "user" {
+				subscribeID := firstArg(args)
+				hasSubscribeID := strings.TrimSpace(subscribeID) != ""
+				if hasSubscribeID && opts.All {
+					return fmt.Errorf("event stop --as user: subscribe_id and --all are mutually exclusive")
+				}
+				if !hasSubscribeID && !opts.All {
+					return fmt.Errorf("event stop --as user: subscribe_id is required unless --all is set")
+				}
+				return nil
+			}
+			if err := rejectChangedFlags(c, "user", "all", "personal-event-base-url", "stream-source-id"); err != nil {
+				return fmt.Errorf("event stop: %w", err)
+			}
+			if len(args) > 0 {
+				return fmt.Errorf("event stop: subscribe_id is only supported with --as user")
+			}
+			return nil
+		},
+		Schema: helpers.LeafSchema{
+			Description: "取消个人事件订阅并停止对应本地消费",
+			DryRun:      &helpers.LeafDryRunDecl{PreviewKind: "request", RemoteReads: false},
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "composite", Availability: "available",
+				Reason: "Reviewed composite workflow: the command deletes remote personal-event subscriptions, interrupts local consumers, updates local state, and may stop the local bus; no single pinned RPC represents the workflow.",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "取消个人事件订阅并停止对应本地消费",
+				UseWhen:      []string{"用户明确要求取消已知 subscribe_id（或清理全部）并停止消费"},
+				AvoidWhen: []string{
+					"只需检查状态时用 event status",
+					"目标订阅不明确或用户未确认时不要停止",
+				},
+				Examples: []string{"dws event stop SUBSCRIBE_ID --dry-run"},
+			},
+		},
+	})
 	return cmd
 }
 
@@ -1110,20 +1213,6 @@ func eventStopDryRun(cmd *cobra.Command) bool {
 	return value
 }
 
-func eventStopConfirmed(cmd *cobra.Command) bool {
-	value, _ := cmd.Flags().GetBool("yes")
-	return value
-}
-
-func eventStopConfirmationRequired(action string) error {
-	return apperrors.NewValidation(
-		action+"；请先使用 --dry-run 预览，确认后加 --yes 执行",
-		apperrors.WithReason("confirmation_required"),
-		apperrors.WithHint("先以相同参数加 --dry-run 预览；获得用户确认后改用 --yes 执行"),
-		apperrors.WithActions("使用 --dry-run 生成预览", "获得用户确认后使用 --yes 执行"),
-	)
-}
-
 func writeEventStopDryRun(cmd *cobra.Command, identity string, opts personalStopOptions) error {
 	payload := map[string]any{
 		"dry_run":  true,

internal/app/event_personal_command.go

@@ -20,6 +20,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"io"
 	"net/http"
 	"os"
@@ -177,6 +178,28 @@ func newEventSchemaCommand() *cobra.Command {
 		Required:    true,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "local", Availability: "available",
+				Reason: "命令读取 CLI 内置的个人事件 payload 定义，不绑定 pinned MCP RPC",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
+				UseWhen:      []string{"已知任一公开个人 IM event_key，消费前需要理解输出字段或保守 payload 契约"},
+				AvoidWhen: []string{
+					"查询 CLI 命令参数契约时用顶层 dws schema",
+					"要实际收事件时用 event consume",
+				},
+				Examples: []string{"dws event schema user_im_message_receive_at --flatten --format json"},
+			},
+		},
+	})
 	return cmd
 }
 

internal/app/mcp_url_command.go

@@ -16,6 +16,7 @@ package app
 import (
 	"encoding/json"
 	"fmt"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"strings"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
@@ -81,6 +82,28 @@ func newMCPURLGetCommand(caller edition.ToolCaller) *cobra.Command {
 		Required:    true,
 		Index:       0,
 	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: cli.SafetySpec{
+			Effect: "read", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Schema: helpers.LeafSchema{
+			Description: "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
+			Interface: &helpers.LeafInterfaceDecl{
+				Mode: "composite", Availability: "available",
+				Reason: "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata.",
+			},
+			Selection: helpers.LeafSelectionDecl{
+				AgentSummary: "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
+				UseWhen:      []string{"已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"},
+				AvoidWhen: []string{
+					"只是查询 DWS 已公开命令或参数时使用 dws schema",
+					"用户要求把返回的凭据 URL 发送到群聊、文档、邮件、日志或代码仓库时不要执行或传播",
+				},
+				Examples: []string{"dws mcp url get 10043 --format json"},
+			},
+		},
+	})
 	return cmd
 }
 

internal/app/pat_auth_retry.go

@@ -569,9 +569,9 @@ func handlePatAuthCheck(
 	// In host-controlled PAT mode (driven solely by DINGTALK_DWS_AGENTCODE),
 	// or when flowId is absent, the CLI returns machine-readable JSON to
 	// stderr and leaves UI/polling/retry to the host. `claw-type` is NOT
-	// used for this decision — it is only forwarded on the wire via
-	// the edition default / DWS_AGENT_PRODUCT override and surfaced in
-	// hostControl for traceability.
+	// used for this decision — its edition-fixed value is forwarded on the
+	// wire and surfaced in hostControl for traceability. DWS_AGENT_PRODUCT
+	// does not affect this PAT contract.
 	if hostOwnedPAT || patData.Data.FlowID == "" {
 		if hostOwnedPAT {
 			return executor.Result{}, &apperrors.PATError{RawJSON: enrichPATErrorForHostControl(patErr.RawJSON)}

internal/app/pat_auth_retry_test.go

@@ -1007,11 +1007,11 @@ func TestHandlePatAuthCheck_HostControlledFlowIDPassthrough(t *testing.T) {
 	t.Setenv("DWS_CONFIG_DIR", tmpDir)
 	// Host-owned decision: driven ONLY by DINGTALK_DWS_AGENTCODE.
 	// DINGTALK_AGENT is set to demonstrate it does NOT leak into
-	// hostControl.clawType. With no DWS_AGENT_PRODUCT override the
-	// open-source edition default remains "openClaw".
+	// hostControl.clawType. DWS_AGENT_PRODUCT is also set to demonstrate
+	// that Product does not change the open-source fixed "openClaw" value.
 	t.Setenv(authpkg.AgentCodeEnv, "agt-sales")
 	t.Setenv("DINGTALK_AGENT", "sales-copilot")
-	t.Setenv(agentproduct.EnvName, "")
+	t.Setenv(agentproduct.EnvName, "qwenwork")
 
 	mock := &mockRunner{
 		runFunc: func(ctx context.Context, inv executor.Invocation) (executor.Result, error) {

internal/app/pat_hostcontrol_wire.go

@@ -29,9 +29,8 @@ import (
 //   - Host-owned is triggered iff DINGTALK_DWS_AGENTCODE is non-empty.
 //   - When triggered, `clawType` in the emitted hostControl block MUST be the
 //     exact value the CLI actually injects on the wire. Each edition supplies
-//     its existing default and an optional valid DWS_AGENT_PRODUCT overrides
-//     it. Invalid input falls back here for library compatibility; root command
-//     execution rejects it before network access.
+//     its fixed value; DWS_AGENT_PRODUCT is a separate observability and IM
+//     message-display signal and never affects this PAT value.
 //   - When DINGTALK_DWS_AGENTCODE is empty the provider returns "" so
 //     HostControlBlock yields nil and no hostControl block is emitted.
 func init() {
@@ -59,5 +58,5 @@ func effectiveClawType() string {
 			headers = h.MergeHeaders(headers)
 		}
 	}
-	return resolveEffectiveAgentProduct(headers)
+	return resolveEditionClawType(headers)
 }

internal/app/runner.go

@@ -1005,9 +1005,8 @@ func resolveIdentityHeaders() map[string]string {
 
 	// Inject environment variable based headers for MCP gateway tracking.
 	// DINGTALK_AGENT, if set by the caller, is forwarded verbatim as the
-	// x-dingtalk-agent header. It does NOT influence claw-type (which comes
-	// from the edition default plus the explicit DWS_AGENT_PRODUCT override)
-	// and it does NOT influence the host-owned PAT decision (driven solely by
+	// x-dingtalk-agent header. It does NOT influence the edition-fixed
+	// claw-type or the host-owned PAT decision (driven solely by
 	// DINGTALK_DWS_AGENTCODE).
 	sessionID := os.Getenv(envDingtalkSessionID)
 	if sessionID == "" {
@@ -1068,22 +1067,30 @@ func resolveIdentityHeaders() map[string]string {
 	if fn := edition.Get().MergeHeaders; fn != nil {
 		headers = fn(headers)
 	}
-	// Resolve the Agent Product before credential injection. The credential
-	// hook has a separate contract and must not be able to replace the
-	// request identity used by PAT hostControl serialization.
-	headers = applyAgentProductOverride(headers)
-	agentProduct := headers[agentproduct.HeaderName]
+	if headers == nil {
+		headers = make(map[string]string)
+	}
+
+	// claw-type is the edition-fixed routing/PAT identity. Agent Product is a
+	// separate caller-declared observability and IM-display dimension.
+	clawType := resolveEditionClawType(headers)
+	headers["claw-type"] = clawType
+	headers = applyAgentProductHeader(headers)
+	agentProduct, hasAgentProduct := headers[agentproduct.HeaderName]
 	if fn := edition.Get().EnterpriseCredentialHeaders; fn != nil {
 		headers = fn(headers)
 	}
 	if headers == nil {
 		headers = make(map[string]string)
 	}
-	// DWS_AGENT_PRODUCT is the explicit caller override for the existing
-	// claw-type wire header. Reassert the resolved product after credential
-	// injection so that hook cannot alter identity. Invalid values are ignored
-	// on this best-effort library path; root execution rejects them earlier.
-	headers[agentproduct.HeaderName] = agentProduct
+	// Credential hooks cannot alter either identity dimension. Restore the
+	// fixed claw-type and the validated Product Header (or its absence).
+	headers["claw-type"] = clawType
+	if hasAgentProduct {
+		headers[agentproduct.HeaderName] = agentProduct
+	} else {
+		delete(headers, agentproduct.HeaderName)
+	}
 	return headers
 }
 

internal/app/schema_agent_examples_dry_run_test.go

@@ -36,6 +36,12 @@ var (
 	manualAgentExamplePlaceholderPattern = regexp.MustCompile(`<([^>]+)>`)
 	manualAgentExampleDryRunJSONPattern  = regexp.MustCompile(`(?i)"dry_run"\s*:\s*true`)
 	manualAgentExampleDryRunPlanPattern  = regexp.MustCompile(`(?i)"preview_kind"\s*:\s*"plan"`)
+	// manualAgentExampleDryRunInvocationPattern recognizes the executor
+	// envelope (and the dev connect preview, which mirrors its shape): the
+	// top-level contract is an invocation that merely embeds the would-be
+	// request inside response, so it must classify as invocation, not request.
+	manualAgentExampleDryRunInvocationPattern = regexp.MustCompile(
+		`"kind"\s*:\s*"(?:(?:helper|compat|workflow)_invocation|connect_preview)"`)
 )
 
 // TestManualAgentExamplesContract is the always-on gate. It validates every
@@ -395,6 +401,9 @@ func manualAgentExampleDryRunEvidence(capture manualAgentExampleCapture) (string
 	if manualAgentExampleDryRunJSONPattern.MatchString(capture.Output) && manualAgentExampleDryRunPlanPattern.MatchString(capture.Output) {
 		return cli.DryRunPreviewPlan, true
 	}
+	if manualAgentExampleDryRunJSONPattern.MatchString(capture.Output) && manualAgentExampleDryRunInvocationPattern.MatchString(capture.Output) {
+		return cli.DryRunPreviewInvocation, true
+	}
 	if manualAgentExampleDryRunJSONPattern.MatchString(capture.Output) {
 		return cli.DryRunPreviewRequest, true
 	}
@@ -448,6 +457,37 @@ func TestCrossPlatformCoverageManualAgentExampleDryRunEvidenceClassifiesStructur
 	}
 }
 
+func TestManualAgentExampleDryRunEvidenceClassifiesExecutorEnvelopeAsInvocation(t *testing.T) {
+	// Executor dry-run envelope: invocation at top level, the would-be request
+	// nested inside response — must classify as invocation, never request.
+	envelope := `{
+  "invocation": {"kind": "helper_invocation", "stage": "helper_override", "implemented": false,
+    "dry_run": true, "canonical_product": "devapp", "tool": "create_dev_app"},
+  "response": {"dry_run": true, "request": {"jsonrpc": "2.0", "method": "tools/call"},
+    "note": "execution skipped by --dry-run"}
+}`
+	kind, observed := manualAgentExampleDryRunEvidence(manualAgentExampleCapture{Output: envelope})
+	if !observed || kind != cli.DryRunPreviewInvocation {
+		t.Fatalf("executor envelope classified as kind=%q observed=%v, want invocation", kind, observed)
+	}
+	for _, invKind := range []string{"compat_invocation", "workflow_invocation", "connect_preview"} {
+		out := strings.Replace(envelope, "helper_invocation", invKind, 1)
+		if kind, ok := manualAgentExampleDryRunEvidence(manualAgentExampleCapture{Output: out}); !ok || kind != cli.DryRunPreviewInvocation {
+			t.Fatalf("kind %q envelope classified as %q/%v, want invocation", invKind, kind, ok)
+		}
+	}
+	// A bare MCP dry-run document has no invocation kind and stays request.
+	mcpDoc := `{"dry_run": true, "executed": false, "tool": "get_dev_app", "arguments": {}}`
+	if kind, ok := manualAgentExampleDryRunEvidence(manualAgentExampleCapture{Output: mcpDoc}); !ok || kind != cli.DryRunPreviewRequest {
+		t.Fatalf("bare MCP dry-run classified as %q/%v, want request", kind, ok)
+	}
+	// Plan still wins over an invocation-shaped payload.
+	planDoc := `{"dry_run": true, "preview_kind": "plan", "kind": "helper_invocation"}`
+	if kind, ok := manualAgentExampleDryRunEvidence(manualAgentExampleCapture{Output: planDoc}); !ok || kind != cli.DryRunPreviewPlan {
+		t.Fatalf("plan precedence broken: %q/%v", kind, ok)
+	}
+}
+
 func manualAgentExamplePromptObserved(output string) bool {
 	normalized := strings.ToLower(output)
 	for _, marker := range []string{

internal/app/schema_contract_test.go

@@ -458,14 +458,14 @@ func TestPromptingWritesRequireUserConfirmation(t *testing.T) {
 		"sheet.delete_pivot_table": "medium",
 	}
 	wantSources := map[string]string{
-		"attendance.class_create":  "internal/cli/schema_hints/metadata/attendance.json",
-		"attendance.class_update":  "internal/cli/schema_hints/metadata/attendance.json",
-		"doc.delete_comment":       "internal/cli/schema_hints/metadata/doc.json",
-		"doc.version_revert":       "internal/cli/schema_hints/metadata/doc.json",
-		"drive.publish_set":        "internal/cli/schema_hints/metadata/drive.json",
-		"drive.publish_unset":      "internal/cli/schema_hints/metadata/drive.json",
-		"sheet.chart_delete":       "internal/cli/schema_hints/metadata/sheet.json",
-		"sheet.delete_pivot_table": "internal/cli/schema_hints/metadata/sheet.json",
+		"attendance.class_create":  "corecmd.contract",
+		"attendance.class_update":  "corecmd.contract",
+		"doc.delete_comment":       "corecmd.contract",
+		"doc.version_revert":       "corecmd.contract",
+		"drive.publish_set":        "corecmd.contract",
+		"drive.publish_unset":      "corecmd.contract",
+		"sheet.chart_delete":       "corecmd.contract",
+		"sheet.delete_pivot_table": "corecmd.contract",
 	}
 	canonicals := make([]string, 0, len(wantEffects))
 	for canonical := range wantEffects {

internal/app/schema_interface_disposition_contract_test.go

@@ -8,7 +8,6 @@ import (
 	"encoding/json"
 	"os"
 	"sort"
-	"strings"
 	"testing"
 )
 
@@ -119,11 +118,11 @@ func TestReviewedRoutedInterfacesReachFinalSchema(t *testing.T) {
 					t.Errorf("missing %s provenance", field)
 					continue
 				}
-				if got := schemaContractString(entry["precedence"]); got != "reviewed_explicit" {
-					t.Errorf("%s provenance precedence = %q, want reviewed_explicit", field, got)
+				if got := schemaContractString(entry["precedence"]); got != "contract_final" {
+					t.Errorf("%s provenance precedence = %q, want contract_final", field, got)
 				}
-				if got := schemaContractString(entry["source"]); !strings.HasSuffix(got, test.sourceSuffix) {
-					t.Errorf("%s provenance source = %q, want suffix %q", field, got, test.sourceSuffix)
+				if got := schemaContractString(entry["source"]); got != "corecmd.contract" {
+					t.Errorf("%s provenance source = %q, want corecmd.contract", field, got)
 				}
 			}
 			if got := provenance["interface_ref"]["value"]; got != nil {
@@ -174,11 +173,11 @@ func TestViewGetWrappersUsePinnedGetViewsInterface(t *testing.T) {
 		provenance := schemaContractMap(tool["field_provenance"])
 		for _, field := range []string{"interface_mode", "availability", "interface_ref"} {
 			entry := provenance[field]
-			if got := schemaContractString(entry["precedence"]); got != "reviewed_explicit" {
-				t.Errorf("%s %s precedence = %q, want reviewed_explicit", canonical, field, got)
+			if got := schemaContractString(entry["precedence"]); got != "contract_final" {
+				t.Errorf("%s %s precedence = %q, want contract_final", canonical, field, got)
 			}
-			if got := schemaContractString(entry["source"]); !strings.Contains(got, "internal/cli/schema_hints/metadata/") {
-				t.Errorf("%s %s source = %q, want reviewed interface disposition source", canonical, field, got)
+			if got := schemaContractString(entry["source"]); got != "corecmd.contract" {
+				t.Errorf("%s %s source = %q, want corecmd.contract", canonical, field, got)
 			}
 		}
 	}
@@ -202,29 +201,10 @@ func TestReviewedInterfaceDispositionSourceOwnsRuntimeSurface(t *testing.T) {
 		return value
 	}
 	runtimeSurface := load("../cli/schema_hints/runtime-surface-completeness.json")
-	legacyDispositionKeys := load("../cli/schema_hints/zz-interface-disposition-review.json").Tools
-	dispositions := hintFile{Source: map[string]any{"reviewed": true}, Tools: map[string]map[string]any{}}
-	for _, product := range []string{
-		"attendance", "aitable", "chat", "drive", "event", "sheet", "wiki", "doc", "mail", "todo", "calendar", "conference", "contact", "dev", "devdoc", "ding", "live", "minutes", "oa", "pat", "report", "aisearch",
-	} {
-		path := "../cli/schema_hints/metadata/" + product + ".json"
-		if _, err := os.Stat(path); err != nil {
-			continue
-		}
-		file := load(path)
-		for canonical, hint := range file.Tools {
-			if _, ok := legacyDispositionKeys[canonical]; !ok {
-				continue
-			}
-			trimmed := map[string]any{}
-			for _, field := range []string{"interface_mode", "availability", "interface_ref", "interface_reason"} {
-				if value, exists := hint[field]; exists {
-					trimmed[field] = value
-				}
-			}
-			dispositions.Tools[canonical] = trimmed
-		}
-	}
+	// After hints→declarations migration, disposition facts live in compiled
+	// ContractFinal (corecmd.contract). zz-interface-disposition-review.json
+	// remains the audit key set + expected values for this gate.
+	dispositions := load("../cli/schema_hints/zz-interface-disposition-review.json")
 	if dispositions.Source["reviewed"] != true {
 		t.Fatalf("interface disposition source reviewed = %#v, want true", dispositions.Source["reviewed"])
 	}
@@ -314,11 +294,11 @@ func TestReviewedInterfaceDispositionSourceOwnsRuntimeSurface(t *testing.T) {
 		}
 		for _, field := range fields {
 			entry := provenance[field]
-			if got := schemaContractString(entry["precedence"]); got != "reviewed_explicit" {
-				t.Errorf("%s final %s precedence = %q, want reviewed_explicit", canonical, field, got)
+			if got := schemaContractString(entry["precedence"]); got != "contract_final" {
+				t.Errorf("%s final %s precedence = %q, want contract_final", canonical, field, got)
 			}
-			if got := schemaContractString(entry["source"]); !strings.Contains(got, "internal/cli/schema_hints/metadata/") {
-				t.Errorf("%s final %s source = %q, want reviewed disposition source", canonical, field, got)
+			if got := schemaContractString(entry["source"]); got != "corecmd.contract" {
+				t.Errorf("%s final %s source = %q, want corecmd.contract", canonical, field, got)
 			}
 		}
 	}

internal/app/schema_safety_contract_test.go

@@ -15,45 +15,53 @@ type finalSchemaSafetyWant struct {
 	risk         string
 	confirmation string
 	idempotency  string
+	// provenance is the expected field_provenance precedence; empty defaults
+	// to "reviewed_explicit" (hints path). Contract-declared tools (devapp)
+	// deliver "contract_final".
+	provenance string
 }
 
 func TestReviewedMutationSafetyReachesFinalSchema(t *testing.T) {
+	const declared = "contract_final"
 	wants := []finalSchemaSafetyWant{
-		{canonical: "aitable.form_field_hide", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "idempotent"},
-		{canonical: "chat.dismiss_group", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "drive.recycle_restore", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "minutes.create_speaker_summary", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "sheet.clear_range", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "sheet.batch_update", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "sheet.range_batch_clear", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "sheet.group_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "sheet.sort_filter", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
-		{canonical: "sheet.ungroup_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown"},
+		{canonical: "aitable.form_field_hide", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "idempotent", provenance: declared},
+		{canonical: "chat.dismiss_group", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "drive.recycle_restore", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "minutes.create_speaker_summary", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.clear_range", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.batch_update", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.range_batch_clear", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.group_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.sort_filter", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "sheet.ungroup_dimension", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
 	}
 	assertFinalSchemaSafety(t, wants)
 }
 
 func TestDevAppWriteGuardRequiresFinalSchemaConfirmation(t *testing.T) {
+	// devapp 全树已声明化：provenance 为 contract_final；风险按可逆性分级
+	// （可逆写 medium / 难撤回 high-write / 删除与发布 destructive）。
+	const declared = "contract_final"
 	wants := []finalSchemaSafetyWant{
-		{canonical: "dev.add_dev_app_members", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.apply_dev_app_permissions", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.create_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.create_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.delete_dev_app", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.disable_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.disable_dev_app_robot", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.enable_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.enable_dev_app_robot", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.publish_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.remove_dev_app_members", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.remove_dev_app_permissions", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.set_extension_robot_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.set_extension_webapp_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.submit_robot_create_task", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.subscribe_dev_app_events", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.unsubscribe_dev_app_events", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.update_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
-		{canonical: "dev.update_dev_app_security_config", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown"},
+		{canonical: "dev.add_dev_app_members", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.apply_dev_app_permissions", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.create_dev_app", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.create_dev_app_version", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.delete_dev_app", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.disable_dev_app", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.disable_dev_app_robot", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.enable_dev_app", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.enable_dev_app_robot", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.publish_dev_app_version", effect: "destructive", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.remove_dev_app_members", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.remove_dev_app_permissions", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.set_extension_robot_config", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.set_extension_webapp_config", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.submit_robot_create_task", effect: "write", risk: "high", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.subscribe_dev_app_events", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.unsubscribe_dev_app_events", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.update_dev_app", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "dev.update_dev_app_security_config", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
 	}
 	assertFinalSchemaSafety(t, wants)
 }
@@ -77,13 +85,17 @@ func assertFinalSchemaSafety(t *testing.T, wants []finalSchemaSafetyWant) {
 				"confirmation": want.confirmation,
 				"idempotency":  want.idempotency,
 			}
+			wantProvenance := want.provenance
+			if wantProvenance == "" {
+				wantProvenance = "reviewed_explicit"
+			}
 			provenance := schemaContractMap(tool["field_provenance"])
 			for field, expected := range values {
 				if got := schemaContractString(tool[field]); got != expected {
 					t.Errorf("%s = %q, want %q", field, got, expected)
 				}
-				if got := schemaContractString(provenance[field]["precedence"]); got != "reviewed_explicit" {
-					t.Errorf("%s provenance precedence = %q, want reviewed_explicit", field, got)
+				if got := schemaContractString(provenance[field]["precedence"]); got != wantProvenance {
+					t.Errorf("%s provenance precedence = %q, want %s", field, got, wantProvenance)
 				}
 			}
 		})

internal/cli/contract_final.go

@@ -0,0 +1,79 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"sync"
+
+	"github.com/spf13/cobra"
+)
+
+// ContractFinalPayload is the Contract-authored final Schema leaf overlay.
+// Registered in-process by the framework; Schema assembly reads it as
+// pass-through. No JSON bridge. Treat as read-only after Register.
+type ContractFinalPayload struct {
+	Title       string
+	Description string
+	Positionals []RuntimeSchemaPositional
+	Safety      *SafetySpec
+	DryRun      *DryRunSpec
+	Interface   *InterfaceSpec
+	Selection   *SelectionSpec
+	Identity    *ToolIdentitySpec
+}
+
+var contractFinalByCommand sync.Map // *cobra.Command → *ContractFinalPayload
+
+// RegisterRuntimeContractFinal stores the typed final Schema overlay for a leaf.
+// Light runtime write: one map store, no JSON, no deep clone.
+func RegisterRuntimeContractFinal(cmd *cobra.Command, payload ContractFinalPayload) {
+	if cmd == nil {
+		return
+	}
+	AnnotateRuntimeContract(cmd)
+	p := payload
+	contractFinalByCommand.Store(cmd, &p)
+}
+
+// RuntimeContractFinal returns the registered final Schema overlay (read-only).
+func RuntimeContractFinal(cmd *cobra.Command) (ContractFinalPayload, bool) {
+	if cmd == nil {
+		return ContractFinalPayload{}, false
+	}
+	raw, ok := contractFinalByCommand.Load(cmd)
+	if !ok {
+		return ContractFinalPayload{}, false
+	}
+	p, ok := raw.(*ContractFinalPayload)
+	if !ok || p == nil {
+		return ContractFinalPayload{}, false
+	}
+	return *p, true
+}
+
+// HasRuntimeContractFinal reports whether the leaf has a registered final overlay.
+func HasRuntimeContractFinal(cmd *cobra.Command) bool {
+	if cmd == nil {
+		return false
+	}
+	_, ok := contractFinalByCommand.Load(cmd)
+	return ok
+}
+
+// ClearRuntimeContractFinalForTest removes a registration (tests only).
+func ClearRuntimeContractFinalForTest(cmd *cobra.Command) {
+	if cmd != nil {
+		contractFinalByCommand.Delete(cmd)
+	}
+}

internal/cli/contract_final_consistency_external_test.go

@@ -0,0 +1,354 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package cli_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+)
+
+// TestAllCommandsContractFinalConsistentWithLiveAndEmbeddedCatalog walks every
+// reviewed registry leaf and checks, one by one:
+//  1. PrimaryCommand has runtime ContractFinal (command-side declaration)
+//  2. Live assembly ToolSpec fields match that ContractFinal
+//  3. Embedded full-leaf shard fields match live ToolSpec (incl. examples)
+func TestAllCommandsContractFinalConsistentWithLiveAndEmbeddedCatalog(t *testing.T) {
+	root := app.NewSchemaSourceRootCommand()
+	liveReg, err := cli.AssembleSchemaRegistry(root)
+	if err != nil {
+		t.Fatalf("AssembleSchemaRegistry(live) error = %v", err)
+	}
+	embedByCanon, err := loadEmbeddedFullLeafTools()
+	if err != nil {
+		t.Fatalf("load embedded full leaf shards: %v", err)
+	}
+
+	effective, err := cli.BuildEffectiveCommandRegistry(root)
+	if err != nil {
+		t.Fatalf("BuildEffectiveCommandRegistry() error = %v", err)
+	}
+	bound, err := cli.BindEffectiveCommandRegistry(root, effective)
+	if err != nil {
+		t.Fatalf("BindEffectiveCommandRegistry() error = %v", err)
+	}
+
+	liveByCanon := indexLiveTools(liveReg)
+
+	type row struct {
+		canonical string
+		cliPath   string
+		status    string
+		detail    string
+	}
+	rows := make([]row, 0, len(bound.Commands))
+	var failCount int
+	checked := 0
+
+	canonOrder := make([]string, 0, len(bound.Commands))
+	boundByCanon := make(map[string]cli.BoundCommandSpec, len(bound.Commands))
+	for _, cmd := range bound.Commands {
+		if cmd.CanonicalPath == "" {
+			continue
+		}
+		canonOrder = append(canonOrder, cmd.CanonicalPath)
+		boundByCanon[cmd.CanonicalPath] = cmd
+	}
+	sort.Strings(canonOrder)
+
+	for _, canonical := range canonOrder {
+		cmd := boundByCanon[canonical]
+		cliPath := cmd.PrimaryCLIPath
+		liveTool, ok := liveByCanon[canonical]
+		if !ok {
+			failCount++
+			rows = append(rows, row{canonical, cliPath, "FAIL", "absent from live registry"})
+			continue
+		}
+		embedTool, ok := embedByCanon[canonical]
+		if !ok {
+			failCount++
+			rows = append(rows, row{canonical, cliPath, "FAIL", "absent from embedded full leaf shard"})
+			continue
+		}
+		final, has := cli.RuntimeContractFinal(cmd.PrimaryCommand)
+		if !has {
+			failCount++
+			rows = append(rows, row{canonical, cliPath, "FAIL", "no RuntimeContractFinal on PrimaryCommand"})
+			continue
+		}
+		checked++
+		problems := compareFinalToLive(canonical, final, liveTool)
+		problems = append(problems, compareLiveToEmbedded(canonical, liveTool, embedTool)...)
+		if len(problems) > 0 {
+			failCount++
+			rows = append(rows, row{canonical, cliPath, "FAIL", strings.Join(problems, "; ")})
+			continue
+		}
+		if liveTool.MetadataSource != "corecmd.contract" {
+			failCount++
+			rows = append(rows, row{canonical, cliPath, "FAIL", "metadata_source=" + liveTool.MetadataSource})
+			continue
+		}
+		rows = append(rows, row{canonical, cliPath, "OK", "ContractFinal=live=catalog"})
+	}
+
+	reportPath := filepath.Join(t.TempDir(), "contract_final_per_command.txt")
+	var b strings.Builder
+	for i, r := range rows {
+		line := fmt.Sprintf("%04d %s %-48s %-60s %s\n", i+1, r.status, r.canonical, r.cliPath, r.detail)
+		b.WriteString(line)
+		if r.status != "OK" {
+			t.Errorf("%s", strings.TrimSpace(line))
+		}
+	}
+	summary := fmt.Sprintf("SUMMARY checked=%d fail=%d ok=%d live=%d embed=%d\n",
+		checked, failCount, checked-failCount, len(liveByCanon), len(embedByCanon))
+	b.WriteString(summary)
+	if err := os.WriteFile(reportPath, []byte(b.String()), 0o644); err != nil {
+		t.Fatalf("write report: %v", err)
+	}
+
+	t.Logf("per-command report: %s", reportPath)
+	t.Logf("%s", strings.TrimSpace(summary))
+	// Print every line so -v shows 逐个检查.
+	for _, r := range rows {
+		t.Logf("%s %-48s %s", r.status, r.canonical, r.cliPath)
+	}
+
+	if failCount > 0 {
+		t.Fatalf("per-command consistency failed: %d/%d", failCount, len(rows))
+	}
+	if checked != 845 {
+		t.Fatalf("checked = %d, want 845 reviewed tools", checked)
+	}
+	if err := cli.ValidateEmbeddedRuntimeSchemaCompleteness(app.NewSchemaSourceRootCommand()); err != nil {
+		t.Fatalf("ValidateEmbeddedRuntimeSchemaCompleteness() error = %v", err)
+	}
+}
+
+type liveToolView struct {
+	Description     string
+	MetadataSource  string
+	Effect          string
+	Risk            string
+	Confirmation    string
+	Idempotency     string
+	InterfaceMode   string
+	Availability    string
+	InterfacePID    string
+	InterfaceRPC    string
+	InterfaceReason string
+	AgentSummary    string
+	UseWhen         []string
+	AvoidWhen       []string
+	Examples        []string
+}
+
+type embedToolView struct {
+	Description    string
+	MetadataSource string
+	Effect         string
+	Risk           string
+	Confirmation   string
+	Idempotency    string
+	InterfaceMode  string
+	Availability   string
+	InterfacePID   string
+	InterfaceRPC   string
+	AgentSummary   string
+	UseWhen        []string
+	AvoidWhen      []string
+	Examples       []string
+}
+
+func indexLiveTools(reg cli.SchemaRegistry) map[string]liveToolView {
+	out := make(map[string]liveToolView)
+	for _, product := range reg.Products {
+		for _, tool := range product.Tools {
+			view := liveToolView{
+				Description:     tool.Description,
+				MetadataSource:  tool.MetadataSource,
+				Effect:          tool.Safety.Effect,
+				Risk:            tool.Safety.Risk,
+				Confirmation:    tool.Safety.Confirmation,
+				Idempotency:     tool.Safety.Idempotency,
+				InterfaceMode:   tool.Interface.Mode,
+				Availability:    tool.Interface.Availability,
+				InterfaceReason: tool.Interface.Reason,
+				AgentSummary:    tool.Selection.AgentSummary,
+				UseWhen:         append([]string(nil), tool.Selection.UseWhen...),
+				AvoidWhen:       append([]string(nil), tool.Selection.AvoidWhen...),
+				Examples:        append([]string(nil), tool.Selection.Examples...),
+			}
+			if tool.Interface.Ref != nil {
+				view.InterfacePID = tool.Interface.Ref.ProductID
+				view.InterfaceRPC = tool.Interface.Ref.RPCName
+			}
+			out[tool.Identity.CanonicalPath] = view
+		}
+	}
+	return out
+}
+
+func repoCLIDir() string {
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		return "."
+	}
+	return filepath.Dir(file)
+}
+
+func loadEmbeddedFullLeafTools() (map[string]embedToolView, error) {
+	toolsDir := filepath.Join(repoCLIDir(), "schema_catalog", "tools")
+	entries, err := os.ReadDir(toolsDir)
+	if err != nil {
+		return nil, err
+	}
+	out := make(map[string]embedToolView)
+	for _, ent := range entries {
+		if ent.IsDir() || !strings.HasSuffix(ent.Name(), ".json") {
+			continue
+		}
+		data, err := os.ReadFile(filepath.Join(toolsDir, ent.Name()))
+		if err != nil {
+			return nil, err
+		}
+		var shard struct {
+			Tools map[string]map[string]any `json:"tools"`
+		}
+		if err := json.Unmarshal(data, &shard); err != nil {
+			return nil, fmt.Errorf("%s: %w", ent.Name(), err)
+		}
+		for key, raw := range shard.Tools {
+			canonical := asString(raw["canonical_path"])
+			if canonical == "" {
+				canonical = key
+			}
+			view := embedToolView{
+				Description:    asString(raw["description"]),
+				MetadataSource: asString(raw["metadata_source"]),
+				Effect:         asString(raw["effect"]),
+				Risk:           asString(raw["risk"]),
+				Confirmation:   asString(raw["confirmation"]),
+				Idempotency:    asString(raw["idempotency"]),
+				InterfaceMode:  asString(raw["interface_mode"]),
+				Availability:   asString(raw["availability"]),
+				AgentSummary:   asString(raw["agent_summary"]),
+				UseWhen:        asStringSlice(raw["use_when"]),
+				AvoidWhen:      asStringSlice(raw["avoid_when"]),
+				Examples:       asStringSlice(raw["examples"]),
+			}
+			if ref, ok := raw["interface_ref"].(map[string]any); ok {
+				view.InterfacePID = asString(ref["product_id"])
+				view.InterfaceRPC = asString(ref["rpc_name"])
+			}
+			out[canonical] = view
+		}
+	}
+	return out, nil
+}
+
+func compareFinalToLive(canonical string, final cli.ContractFinalPayload, tool liveToolView) []string {
+	var problems []string
+	add := func(field, want, got string) {
+		if strings.TrimSpace(want) == "" {
+			return
+		}
+		if strings.TrimSpace(want) != strings.TrimSpace(got) {
+			problems = append(problems, fmt.Sprintf("%s: final=%q live=%q", field, want, got))
+		}
+	}
+	if final.Description != "" {
+		add("description", final.Description, tool.Description)
+	}
+	if final.Safety != nil {
+		add("effect", final.Safety.Effect, tool.Effect)
+		add("risk", final.Safety.Risk, tool.Risk)
+		add("confirmation", final.Safety.Confirmation, tool.Confirmation)
+		add("idempotency", final.Safety.Idempotency, tool.Idempotency)
+	}
+	if final.Interface != nil {
+		add("interface_mode", final.Interface.Mode, tool.InterfaceMode)
+		add("availability", final.Interface.Availability, tool.Availability)
+		add("interface_reason", final.Interface.Reason, tool.InterfaceReason)
+		if final.Interface.Ref != nil {
+			add("interface_product", final.Interface.Ref.ProductID, tool.InterfacePID)
+			add("interface_rpc", final.Interface.Ref.RPCName, tool.InterfaceRPC)
+		}
+	}
+	if final.Selection != nil {
+		add("agent_summary", final.Selection.AgentSummary, tool.AgentSummary)
+		if !reflect.DeepEqual(final.Selection.UseWhen, tool.UseWhen) {
+			problems = append(problems, "use_when mismatch")
+		}
+		if !reflect.DeepEqual(final.Selection.AvoidWhen, tool.AvoidWhen) {
+			problems = append(problems, "avoid_when mismatch")
+		}
+		if !reflect.DeepEqual(final.Selection.Examples, tool.Examples) {
+			problems = append(problems, "examples mismatch")
+		}
+	}
+	_ = canonical
+	return problems
+}
+
+func compareLiveToEmbedded(canonical string, live liveToolView, embed embedToolView) []string {
+	var problems []string
+	add := func(field, a, b string) {
+		if strings.TrimSpace(a) != strings.TrimSpace(b) {
+			problems = append(problems, fmt.Sprintf("%s: live=%q embed=%q", field, a, b))
+		}
+	}
+	add("description", live.Description, embed.Description)
+	add("effect", live.Effect, embed.Effect)
+	add("risk", live.Risk, embed.Risk)
+	add("confirmation", live.Confirmation, embed.Confirmation)
+	add("idempotency", live.Idempotency, embed.Idempotency)
+	add("interface_mode", live.InterfaceMode, embed.InterfaceMode)
+	add("availability", live.Availability, embed.Availability)
+	add("agent_summary", live.AgentSummary, embed.AgentSummary)
+	add("metadata_source", live.MetadataSource, embed.MetadataSource)
+	add("interface_product", live.InterfacePID, embed.InterfacePID)
+	add("interface_rpc", live.InterfaceRPC, embed.InterfaceRPC)
+	if !reflect.DeepEqual(live.UseWhen, embed.UseWhen) {
+		problems = append(problems, "use_when live!=embed")
+	}
+	if !reflect.DeepEqual(live.AvoidWhen, embed.AvoidWhen) {
+		problems = append(problems, "avoid_when live!=embed")
+	}
+	if !reflect.DeepEqual(live.Examples, embed.Examples) {
+		problems = append(problems, "examples live!=embed")
+	}
+	_ = canonical
+	return problems
+}
+
+func asString(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+func asStringSlice(v any) []string {
+	raw, ok := v.([]any)
+	if !ok {
+		return nil
+	}
+	out := make([]string, 0, len(raw))
+	for _, item := range raw {
+		if s, ok := item.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}

internal/cli/contract_final_test.go

@@ -0,0 +1,158 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestContractFinalTypedRegistryNoJSON(t *testing.T) {
+	cmd := &cobra.Command{Use: "x"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(cmd) })
+
+	RegisterRuntimeContractFinal(cmd, ContractFinalPayload{
+		Title: "T",
+		Safety: &SafetySpec{
+			Effect: "write", Confirmation: "user_required", Idempotency: "retryable",
+		},
+		Selection: &SelectionSpec{AgentSummary: "sum", UseWhen: []string{"u"}},
+		Identity:  &ToolIdentitySpec{ProductID: "p", Name: "n"},
+	})
+	if cmd.Annotations != nil {
+		if _, ok := cmd.Annotations["dws.schema.final"]; ok {
+			t.Fatal("must not write JSON annotation dws.schema.final")
+		}
+	}
+	got, ok := RuntimeContractFinal(cmd)
+	if !ok || got.Title != "T" || got.Safety == nil || got.Safety.Idempotency != "retryable" {
+		t.Fatalf("got %#v ok=%v", got, ok)
+	}
+	if got.Selection == nil || got.Selection.Reviewed != nil {
+		t.Fatalf("selection must not carry reviewed fields: %#v", got.Selection)
+	}
+}
+
+func TestRuntimeToolSpecFromContractFinalPassThrough(t *testing.T) {
+	cmd := &cobra.Command{Use: "create", Short: "s", Long: "l"}
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(cmd) })
+	cmd.Flags().String("mode", "", "usage")
+	AnnotateRuntimeFlag(cmd, "mode", "mode", "string", false, "")
+	RegisterRuntimeContractFinal(cmd, ContractFinalPayload{
+		Title: "Final Title",
+		Safety: &SafetySpec{
+			Effect: "write", Confirmation: "user_required", Idempotency: "none",
+		},
+		DryRun: &DryRunSpec{PreviewKind: DryRunPreviewInvocation},
+		Selection: &SelectionSpec{
+			AgentSummary: "from contract",
+			UseWhen:      []string{"create things"},
+		},
+		Identity: &ToolIdentitySpec{
+			ProductID: "dev", Name: "create_thing", CanonicalPath: "dev.create_thing",
+		},
+	})
+
+	entry := runtimeSchemaEntry{
+		ProductID:      "dev",
+		ToolName:       "create_thing",
+		CLIName:        "create",
+		CLIPath:        "dev create",
+		PrimaryCLIPath: "dev create",
+		ProductName:    "Dev",
+		Command:        cmd,
+		Source:         "test",
+	}
+	spec, err := runtimeToolSpecFromContractFinal(entry, mustFinal(t, cmd), runtimeSchemaMetadataSources{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if spec.Title != "Final Title" {
+		t.Fatalf("title = %q", spec.Title)
+	}
+	if spec.Safety.Confirmation != "user_required" || spec.Safety.Idempotency != "none" {
+		t.Fatalf("safety = %#v", spec.Safety)
+	}
+	if spec.DryRun == nil || spec.DryRun.PreviewKind != DryRunPreviewInvocation {
+		t.Fatalf("dry_run = %#v", spec.DryRun)
+	}
+	if spec.Selection.AgentSummary != "from contract" {
+		t.Fatalf("selection = %#v", spec.Selection)
+	}
+	if spec.MetadataSource != "corecmd.contract" {
+		t.Fatalf("metadata_source = %q", spec.MetadataSource)
+	}
+	if len(spec.Parameters) != 1 || spec.Parameters[0].Name != "mode" {
+		t.Fatalf("parameters = %#v", spec.Parameters)
+	}
+}
+
+func TestRuntimeToolSpecFromContractFinalIdentityMismatchFails(t *testing.T) {
+	entry := runtimeSchemaEntry{
+		ProductID:      "dev",
+		ToolName:       "create_thing",
+		CLIName:        "create",
+		CLIPath:        "dev create",
+		PrimaryCLIPath: "dev create",
+		Command:        &cobra.Command{Use: "create"},
+		Source:         "test",
+	}
+	for name, id := range map[string]ToolIdentitySpec{
+		"wrong name":           {Name: "delete_thing"},
+		"wrong canonical path": {CanonicalPath: "dev.delete_thing"},
+		"wrong product":        {ProductID: "other"},
+		"wrong cli path":       {CLIPath: "dev delete"},
+		"wrong aliases":        {Aliases: []string{"dev rm"}},
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := runtimeToolSpecFromContractFinal(entry, ContractFinalPayload{Identity: &id}, runtimeSchemaMetadataSources{})
+			if err == nil {
+				t.Fatal("declared identity conflicting with bound entry must fail assembly")
+			}
+		})
+	}
+	consistent := ContractFinalPayload{Identity: &ToolIdentitySpec{
+		ProductID: "dev", Name: "create_thing", CLIName: "create",
+		CanonicalPath: "dev.create_thing", CLIPath: "dev create",
+		PrimaryCLIPath: "dev create", Source: "test",
+	}}
+	if _, err := runtimeToolSpecFromContractFinal(entry, consistent, runtimeSchemaMetadataSources{}); err != nil {
+		t.Fatalf("declared identity matching bound entry must pass: %v", err)
+	}
+}
+
+func TestRuntimeToolSpecFromContractFinalRejectsReviewedSelection(t *testing.T) {
+	reviewed := true
+	entry := runtimeSchemaEntry{
+		ProductID: "dev",
+		ToolName:  "create_thing",
+		Command:   &cobra.Command{Use: "create"},
+	}
+	_, err := runtimeToolSpecFromContractFinal(entry, ContractFinalPayload{
+		Selection: &SelectionSpec{AgentSummary: "sum", Reviewed: &reviewed},
+	}, runtimeSchemaMetadataSources{})
+	if err == nil {
+		t.Fatal("declaration payload carrying Reviewed must fail assembly (reviewed is legacy-path only)")
+	}
+}
+
+func mustFinal(t *testing.T, cmd *cobra.Command) ContractFinalPayload {
+	t.Helper()
+	final, ok := RuntimeContractFinal(cmd)
+	if !ok {
+		t.Fatal("missing final")
+	}
+	return final
+}

internal/cli/contract_safety_homology_external_test.go

@@ -0,0 +1,249 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package cli_test
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+)
+
+// TestUserRequiredSafetyHomologyWithRuntimeGate proves Catalog Safety and the
+// executable confirmation gate share one source for every live user_required leaf:
+//
+//  1. ContractFinal.Safety.Confirmation == live ToolSpec.Confirmation
+//  2. Runtime gate is installed: DeclareLeafMetadata (HasContractConfirmSafety),
+//     Sheet protect marker, or framework NewCommand/Shortcut RunE (verified by
+//     closed-stdin Execute → confirmation_required / 用户取消了操作 without --yes)
+func TestUserRequiredSafetyHomologyWithRuntimeGate(t *testing.T) {
+	root := app.NewSchemaSourceRootCommand()
+	if root.PersistentFlags().Lookup("yes") == nil {
+		root.PersistentFlags().Bool("yes", false, "")
+	}
+	if root.PersistentFlags().Lookup("dry-run") == nil {
+		root.PersistentFlags().Bool("dry-run", false, "")
+	}
+
+	liveReg, err := cli.AssembleSchemaRegistry(root)
+	if err != nil {
+		t.Fatalf("AssembleSchemaRegistry: %v", err)
+	}
+	effective, err := cli.BuildEffectiveCommandRegistry(root)
+	if err != nil {
+		t.Fatalf("BuildEffectiveCommandRegistry: %v", err)
+	}
+	bound, err := cli.BindEffectiveCommandRegistry(root, effective)
+	if err != nil {
+		t.Fatalf("BindEffectiveCommandRegistry: %v", err)
+	}
+
+	liveByCanon := make(map[string]string) // canonical → confirmation
+	liveToolByCanon := make(map[string]cli.ToolSpec)
+	for _, product := range liveReg.Products {
+		for _, tool := range product.Tools {
+			liveByCanon[tool.Identity.CanonicalPath] = strings.TrimSpace(tool.Safety.Confirmation)
+			liveToolByCanon[tool.Identity.CanonicalPath] = tool
+		}
+	}
+
+	type row struct {
+		canonical string
+		cliPath   string
+		gate      string
+		detail    string
+	}
+	var fails []row
+	var okRows []row
+	checked := 0
+
+	canonOrder := make([]string, 0, len(bound.Commands))
+	boundByCanon := make(map[string]cli.BoundCommandSpec, len(bound.Commands))
+	for _, cmd := range bound.Commands {
+		if cmd.CanonicalPath == "" {
+			continue
+		}
+		canonOrder = append(canonOrder, cmd.CanonicalPath)
+		boundByCanon[cmd.CanonicalPath] = cmd
+	}
+	sort.Strings(canonOrder)
+
+	for _, canonical := range canonOrder {
+		cmd := boundByCanon[canonical]
+		leaf := cmd.PrimaryCommand
+		if leaf == nil {
+			fails = append(fails, row{canonical, cmd.PrimaryCLIPath, "", "nil PrimaryCommand"})
+			continue
+		}
+		final, hasFinal := cli.RuntimeContractFinal(leaf)
+		if !hasFinal || final.Safety == nil {
+			continue
+		}
+		conf := strings.TrimSpace(final.Safety.Confirmation)
+		if conf != "user_required" {
+			continue
+		}
+		checked++
+		cliPath := cmd.PrimaryCLIPath
+
+		liveConf, ok := liveByCanon[canonical]
+		if !ok {
+			fails = append(fails, row{canonical, cliPath, "", "absent from live registry"})
+			continue
+		}
+		if liveConf != "user_required" {
+			fails = append(fails, row{canonical, cliPath, "", fmt.Sprintf(
+				"ContractFinal=user_required but live ToolSpec.Confirmation=%q", liveConf)})
+			continue
+		}
+
+		gate := ""
+		switch {
+		case helpers.HasContractConfirmSafety(leaf) && helpers.HasSheetMutationConfirmationGuard(leaf):
+			gate = "declare_leaf+sheet_marker"
+		case helpers.HasContractConfirmSafety(leaf):
+			gate = "declare_leaf_confirm"
+		case helpers.HasSheetMutationConfirmationGuard(leaf):
+			gate = "sheet_protect"
+		default:
+			// NewLeafCommand / Shortcut: NewCommand registers ContractFinal from the
+			// same SafetySpec it wires into ConfirmSafety. Prove that SafetySpec is
+			// still user_required-operable (closed stdin → confirmation gate).
+			leaf.SetIn(strings.NewReader(""))
+			leaf.SetOut(io.Discard)
+			leaf.SetErr(io.Discard)
+			if err := corecmd.ConfirmSafety(leaf, *final.Safety); !isConfirmationGateError(err) {
+				fails = append(fails, row{canonical, cliPath, "", fmt.Sprintf(
+					"framework leaf: ConfirmSafety(ContractFinal.Safety) = %v, want confirmation gate", err)})
+				continue
+			}
+			// Execute without --yes must not succeed (confirm-first or validate-then-confirm).
+			if err := probeConfirmationGate(leaf); err == nil {
+				fails = append(fails, row{canonical, cliPath, "",
+					"framework leaf: Execute without --yes succeeded"})
+				continue
+			}
+			gate = "framework_confirm_safety"
+		}
+		okRows = append(okRows, row{canonical, cliPath, gate, "ok"})
+	}
+
+	if checked == 0 {
+		t.Fatal("no user_required ContractFinal leaves found")
+	}
+	if len(fails) != 0 {
+		for _, f := range fails {
+			t.Errorf("%s (%s): %s", f.canonical, f.cliPath, f.detail)
+		}
+		t.Fatalf("Safety homology failed: %d/%d user_required leaves", len(fails), checked)
+	}
+
+	byGate := map[string]int{}
+	for _, r := range okRows {
+		byGate[r.gate]++
+	}
+	t.Logf("user_required Safety homology OK: %d leaves gates=%v", checked, byGate)
+
+	// Sheet transitional dual gate: every Sheet --yes-only protect marker must
+	// also carry DeclareLeafMetadata ConfirmSafety. A bare sheet_protect leaf
+	// would mean the outer guard was dropped from the homology pair (or the
+	// contract wrap never installed), silently widening authorization.
+	if bare := byGate["sheet_protect"]; bare != 0 {
+		t.Fatalf("transitional Sheet dual gate broken: %d leaf(ves) have sheet_protect without declare_leaf_confirm", bare)
+	}
+	if dual := byGate["declare_leaf+sheet_marker"]; dual == 0 {
+		t.Fatal("expected declare_leaf+sheet_marker leaves for Sheet transitional dual confirmation gate")
+	}
+
+	// Confirm/validate order is asserted by behavior, not by a claim of intent:
+	// a "deferred" annotation can still confirm first at runtime. For every
+	// user_required leaf that publishes a required parameter, an argument-less
+	// invocation must report that missing parameter — reaching confirmation
+	// instead is the RFC §5.1 inversion.
+	//
+	// Two forms declare guard-first ordering deliberately and are exempt: a Spec
+	// ConfirmFirst field (the devapp write contract asserted by
+	// TestEveryDevAppWriteCommandRequiresGuard) and the reviewed Sheet
+	// confirmationGuards table, whose wrapper is --yes-only by design. Both are
+	// declarations, not inferences, so the exemption cannot be reached by
+	// accident.
+	var orderFails []row
+	for _, r := range okRows {
+		leaf := boundByCanon[r.canonical].PrimaryCommand
+		if leaf == nil || !requiresParameter(liveToolByCanon[r.canonical]) {
+			continue
+		}
+		if corecmd.HasDeclaredConfirmFirst(leaf) || helpers.HasSheetMutationConfirmationGuard(leaf) {
+			continue
+		}
+		if err := probeConfirmationGate(leaf); isConfirmationGateError(err) {
+			orderFails = append(orderFails, row{r.canonical, r.cliPath, r.gate,
+				fmt.Sprintf("confirms before reporting a missing required parameter: %v", err)})
+		}
+	}
+	if len(orderFails) != 0 {
+		for _, f := range orderFails {
+			t.Errorf("%s (%s): %s", f.canonical, f.cliPath, f.detail)
+		}
+		t.Fatalf("confirm/validate order invariant failed: %d user_required leaf(ves)", len(orderFails))
+	}
+}
+
+// requiresParameter reports whether the delivered ToolSpec publishes at least
+// one required parameter, i.e. whether an argument-less invocation is expected
+// to fail validation before anything else.
+func requiresParameter(tool cli.ToolSpec) bool {
+	for _, param := range tool.Parameters {
+		if param.Required || param.CLIRequired {
+			return true
+		}
+	}
+	return false
+}
+
+func probeConfirmationGate(leaf *cobra.Command) error {
+	root := leaf.Root()
+	if root == nil {
+		root = leaf
+	}
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	root.SetIn(strings.NewReader(""))
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+
+	// Rebuild args from CommandPath relative to root.
+	path := strings.TrimSpace(strings.TrimPrefix(leaf.CommandPath(), root.CommandPath()))
+	fields := strings.Fields(path)
+	root.SetArgs(fields)
+	return root.Execute()
+}
+
+// isConfirmationGateError reports whether err is the confirmation gate itself.
+//
+// It classifies on the machine-readable reason rather than on prose: a Sheet
+// destructive leaf's missing-flag error embeds the example
+// "（获得用户确认后加 --yes）", so substring matching reported the confirmation gate
+// for a correct validation error. The decline path is the one case that carries
+// no reason, so it is matched by its exact message.
+func isConfirmationGateError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var typed *apperrors.Error
+	if errors.As(err, &typed) && strings.TrimSpace(typed.Reason) == "confirmation_required" {
+		return true
+	}
+	return strings.Contains(err.Error(), "用户取消了操作")
+}

internal/cli/contract_schema_embed_test.go

@@ -0,0 +1,92 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestAnnotateRuntimeRiskEmbedsContractMarker(t *testing.T) {
+	cmd := &cobra.Command{Use: "x"}
+	AnnotateRuntimeRisk(cmd, "write")
+	got, ok := RuntimeContractRisk(cmd)
+	if !ok || got != "write" {
+		t.Fatalf("RuntimeContractRisk = %q %v", got, ok)
+	}
+	if cmd.Annotations[runtimeSchemaContractAnnotation] != "command" {
+		t.Fatalf("contract marker = %q", cmd.Annotations[runtimeSchemaContractAnnotation])
+	}
+	AnnotateRuntimeRisk(cmd, "")
+	if got, _ = RuntimeContractRisk(cmd); got != "write" {
+		t.Fatalf("empty AnnotateRuntimeRisk must be no-op, got %q", got)
+	}
+}
+
+func TestApplyContractRiskToSafety(t *testing.T) {
+	base := SafetySpec{Idempotency: "unknown", Risk: "low", Confirmation: "not_required", Effect: "read"}
+	got := applyContractRiskToSafety(base, "high-risk-write")
+	if got.Effect != "destructive" || got.Risk != "high" || got.Confirmation != "user_required" {
+		t.Fatalf("high-risk overlay = %#v", got)
+	}
+	if got.Idempotency != "unknown" {
+		t.Fatalf("idempotency should be preserved, got %q", got.Idempotency)
+	}
+	got = applyContractRiskToSafety(base, "write")
+	if got.Effect != "write" || got.Risk != "medium" || got.Confirmation != "user_required" {
+		t.Fatalf("write overlay = %#v", got)
+	}
+	got = applyContractRiskToSafety(base, "read")
+	if got.Effect != "read" || got.Risk != "low" || got.Confirmation != "not_required" {
+		t.Fatalf("read overlay = %#v", got)
+	}
+}
+
+func TestAnnotateRuntimeGateDeclareOrAnnotate(t *testing.T) {
+	cmd := &cobra.Command{Use: "x"}
+	if HasDeclaredOrAnnotatedConfirmation(cmd) {
+		t.Fatal("bare command must not claim confirmation coverage")
+	}
+	AnnotateRuntimeGate(cmd, "devAppRequireWriteGuard")
+	got, ok := RuntimeContractGate(cmd)
+	if !ok || got != "devAppRequireWriteGuard" {
+		t.Fatalf("RuntimeContractGate = %q %v", got, ok)
+	}
+	if !HasDeclaredOrAnnotatedConfirmation(cmd) {
+		t.Fatal("annotated gate must satisfy declare-OR-annotate")
+	}
+	if cmd.Annotations[runtimeSchemaContractAnnotation] != "command" {
+		t.Fatalf("contract marker = %q", cmd.Annotations[runtimeSchemaContractAnnotation])
+	}
+}
+
+func TestApplyContractGateToSafety(t *testing.T) {
+	base := SafetySpec{Confirmation: "not_required", Effect: "read", Risk: "low"}
+	got := applyContractGateToSafety(base, "devAppRequireWriteGuard")
+	if got.Confirmation != "user_required" {
+		t.Fatalf("gate must force user_required, got %#v", got)
+	}
+	if got.Effect != "write" || got.EffectSource != "corecmd.contract_gate" {
+		t.Fatalf("gate effect overlay = %#v", got)
+	}
+	if got.Risk != "medium" {
+		t.Fatalf("gate risk overlay = %#v", got)
+	}
+	reviewed := SafetySpec{Confirmation: "not_required", Effect: "destructive", Risk: "high", EffectSource: "reviewed"}
+	got = applyContractGateToSafety(reviewed, "devAppRequireWriteGuard")
+	if got.Effect != "destructive" || got.Risk != "high" || got.Confirmation != "user_required" {
+		t.Fatalf("gate must keep reviewed effect/risk: %#v", got)
+	}
+}

internal/cli/homology_gates_plan_test.go

@@ -0,0 +1,98 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// Planned homology gates (docs/flag-help-schema-homology.md §4). Implementations
+// land incrementally; this test pins the gate ID vocabulary so CI docs and
+// future policy scripts share one checklist.
+var plannedHomologyGateIDs = []string{
+	"HOM-P1", // schema parameters names ≡ cobra local flags
+	"HOM-P2", // type/required/default ≡ Contract/cobra; hints cannot win those
+	"HOM-P3", // schema constraints ≡ Contract Constraints projection
+	"HOM-S1", // Risk write/high-risk → confirmation=user_required + help Safety
+	"HOM-S2", // write-guard path must record honest provenance
+	"HOM-S3", // read Risk must not project user_required without exclusion
+	"HOM-I1", // interface_ref/bindings ⊆ Contract flags; MCP meta creates no flags
+	"HOM-D1", // --help Flags ≡ schema leaf parameters
+}
+
+func TestHomologyDecisionDocPinsPathAAndGateIDs(t *testing.T) {
+	_, thisFile, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("runtime.Caller failed")
+	}
+	doc := filepath.Clean(filepath.Join(filepath.Dir(thisFile), "..", "..", "docs", "flag-help-schema-homology.md"))
+	raw, err := os.ReadFile(doc)
+	if err != nil {
+		t.Fatalf("read homology doc: %v", err)
+	}
+	body := string(raw)
+	for _, needle := range []string{
+		"路径 A",
+		"Contract / LeafSpec 为 CLI 表面权威",
+		"必须嵌入进 Schema",
+		"embedContractIntoSchema",
+		"声明 = 最终数据源",
+		"不得：",
+		"把声明序列化成 JSON 注解再解析",
+		"声明体系里再挂「评审字段」并行权威",
+		"声明（declare）：写什么、写在哪、投影到哪",
+		"契约字段（算声明）",
+		"编排 / 执行字段（不算声明）",
+		"Schema 全覆盖（`ToolSpec` 无空洞）",
+		"dws.schema.runtime_gate",
+		"mcp_passthrough",
+		"不得覆盖 LeafSpec / Shortcut 主路径",
+	} {
+		if !strings.Contains(body, needle) {
+			t.Fatalf("homology doc missing %q", needle)
+		}
+	}
+	for _, id := range plannedHomologyGateIDs {
+		if !strings.Contains(body, id) {
+			t.Fatalf("homology doc missing planned gate ID %s", id)
+		}
+	}
+}
+
+func TestMCPPassthroughAdmissionExcludesLeafAndShortcut(t *testing.T) {
+	_, thisFile, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("runtime.Caller failed")
+	}
+	doc := filepath.Clean(filepath.Join(filepath.Dir(thisFile), "..", "..", "docs", "flag-help-schema-homology.md"))
+	raw, err := os.ReadFile(doc)
+	if err != nil {
+		t.Fatalf("read homology doc: %v", err)
+	}
+	body := string(raw)
+	for _, needle := range []string{
+		"严格 1:1",
+		"全部 `LeafSpec` 命令",
+		"全部 `+shortcut`",
+		"surface_kind=mcp_passthrough",
+	} {
+		if !strings.Contains(body, needle) {
+			t.Fatalf("passthrough admission text missing %q", needle)
+		}
+	}
+}

internal/cli/runtime_schema.go

@@ -49,6 +49,13 @@ const (
 	runtimeSchemaFlagRequiredAnnotation     = "dws.schema.required"
 	runtimeSchemaFlagRequiredWhenAnnotation = "dws.schema.required_when"
 	runtimeSchemaFlagExampleAnnotation      = "dws.schema.example"
+
+	// Contract surface (command / LeafSpec) embedded onto the live Cobra leaf so
+	// Schema generation can project parameters/constraints/Risk without a second
+	// source of truth. See docs/flag-help-schema-homology.md.
+	runtimeSchemaContractAnnotation    = "dws.schema.contract"
+	runtimeSchemaRiskAnnotation        = "dws.schema.risk"
+	runtimeSchemaRuntimeGateAnnotation = "dws.schema.runtime_gate"
 )
 
 // RuntimeSchemaConstraints describes cross-parameter rules that cannot be
@@ -262,6 +269,16 @@ func AnnotateRuntimeRequiredFlags(cmd *cobra.Command, flagNames ...string) {
 	}
 }
 
+// AnnotateRuntimeFlagDescription records the Schema parameter description.
+func AnnotateRuntimeFlagDescription(cmd *cobra.Command, flagName, description string) {
+	if cmd == nil {
+		return
+	}
+	if flag := runtimeCommandFlag(cmd, flagName); flag != nil {
+		setFlagAnnotation(flag, runtimeSchemaFlagDescriptionAnnotation, strings.TrimSpace(description))
+	}
+}
+
 // AnnotateRuntimeFlagRequiredWhen records a conditional CLI requirement. The
 // expression is descriptive metadata and does not alter Cobra validation.
 func AnnotateRuntimeFlagRequiredWhen(cmd *cobra.Command, flagName, expression string) {
@@ -306,6 +323,128 @@ func AnnotateRuntimeFlagExample(cmd *cobra.Command, flagName, example string) {
 	}
 }
 
+// AnnotateRuntimeContract marks a command as carrying a command/LeafSpec
+// Contract surface. Schema assembly treats embedded flag annotations and, when
+// set, AnnotateRuntimeRisk as Contract-authored facts (path A homology).
+func AnnotateRuntimeContract(cmd *cobra.Command) {
+	if cmd == nil {
+		return
+	}
+	setRuntimeCommandAnnotation(cmd, runtimeSchemaContractAnnotation, "command")
+}
+
+// AnnotateRuntimeRisk records the Contract Risk string (read|write|high-risk-write)
+// for Schema Safety projection. Empty risk is a no-op so write-guard leaves that
+// leave Risk unset keep reviewed hint safety.
+func AnnotateRuntimeRisk(cmd *cobra.Command, risk string) {
+	if cmd == nil {
+		return
+	}
+	risk = strings.TrimSpace(risk)
+	if risk == "" {
+		return
+	}
+	AnnotateRuntimeContract(cmd)
+	setRuntimeCommandAnnotation(cmd, runtimeSchemaRiskAnnotation, risk)
+}
+
+// AnnotateRuntimeGate records a non-Risk confirmation path (e.g.
+// devAppRequireWriteGuard). Homology rule: every confirmation fact is either
+// Contract-declared (Risk) or explicitly annotated (this gate / reviewed hints).
+func AnnotateRuntimeGate(cmd *cobra.Command, gate string) {
+	if cmd == nil {
+		return
+	}
+	gate = strings.TrimSpace(gate)
+	if gate == "" {
+		return
+	}
+	AnnotateRuntimeContract(cmd)
+	setRuntimeCommandAnnotation(cmd, runtimeSchemaRuntimeGateAnnotation, gate)
+}
+
+// RuntimeContractRisk returns the Contract Risk annotation when present.
+func RuntimeContractRisk(cmd *cobra.Command) (string, bool) {
+	if cmd == nil || cmd.Annotations == nil {
+		return "", false
+	}
+	risk := strings.TrimSpace(cmd.Annotations[runtimeSchemaRiskAnnotation])
+	if risk == "" {
+		return "", false
+	}
+	return risk, true
+}
+
+// RuntimeContractGate returns the annotated runtime confirmation gate when present.
+func RuntimeContractGate(cmd *cobra.Command) (string, bool) {
+	if cmd == nil || cmd.Annotations == nil {
+		return "", false
+	}
+	gate := strings.TrimSpace(cmd.Annotations[runtimeSchemaRuntimeGateAnnotation])
+	if gate == "" {
+		return "", false
+	}
+	return gate, true
+}
+
+// HasDeclaredOrAnnotatedConfirmation reports whether confirmation semantics are
+// covered by a typed Contract SafetySpec, the legacy Shortcut Risk bridge, or
+// an explicit runtime_gate annotation.
+func HasDeclaredOrAnnotatedConfirmation(cmd *cobra.Command) bool {
+	if final, ok := RuntimeContractFinal(cmd); ok && final.Safety != nil &&
+		strings.TrimSpace(final.Safety.Confirmation) != "" {
+		return true
+	}
+	if _, ok := RuntimeContractRisk(cmd); ok {
+		return true
+	}
+	_, ok := RuntimeContractGate(cmd)
+	return ok
+}
+
+// applyContractRiskToSafety overlays Schema Safety fields from an embedded
+// Contract Risk value. Path A: Contract wins effect/risk/confirmation for the
+// managed surface; other Safety fields (e.g. idempotency) are preserved.
+func applyContractRiskToSafety(base SafetySpec, contractRisk string) SafetySpec {
+	out := base
+	switch strings.TrimSpace(contractRisk) {
+	case "write":
+		out.Effect = "write"
+		out.EffectSource = "corecmd.contract"
+		out.Risk = "medium"
+		out.Confirmation = "user_required"
+	case "high-risk-write":
+		out.Effect = "destructive"
+		out.EffectSource = "corecmd.contract"
+		out.Risk = "high"
+		out.Confirmation = "user_required"
+	case "read":
+		out.Effect = "read"
+		out.EffectSource = "corecmd.contract"
+		out.Risk = "low"
+		out.Confirmation = "not_required"
+	}
+	return out
+}
+
+// applyContractGateToSafety ensures a write-guard annotation cannot leave Schema
+// claiming confirmation is not required. Reviewed effect/risk are kept when set.
+func applyContractGateToSafety(base SafetySpec, gate string) SafetySpec {
+	out := base
+	if strings.TrimSpace(gate) == "" {
+		return out
+	}
+	out.Confirmation = "user_required"
+	if out.Effect == "" || out.Effect == "read" {
+		out.Effect = "write"
+		out.EffectSource = "corecmd.contract_gate"
+	}
+	if out.Risk == "" || out.Risk == "low" {
+		out.Risk = "medium"
+	}
+	return out
+}
+
 // AnnotateRuntimeConstraints records command-level parameter relationships.
 func AnnotateRuntimeConstraints(cmd *cobra.Command, constraints RuntimeSchemaConstraints) {
 	if cmd == nil {

internal/cli/schema_agent_metadata/aisearch.json

@@ -3,7 +3,7 @@
   "tools": {
     "aisearch behavior": {
       "agent_summary": "搜索发送/创建/分享/编辑/接收等明确行为记录",
-      "agent_summary_source": "dws-agent-selection/aisearch",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "只按主题找内容本身时用 aisearch enterprise",
@@ -11,7 +11,7 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws aisearch behavior --types mail --behavior-type send --direction \"我-\u003e汐峰\" --format json",
         "dws aisearch behavior --queries \"智能化方案\" --types document --behavior-type create --format json"
@@ -19,33 +19,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "搜索发送/创建/分享/编辑/接收等明确行为记录",
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "搜索发送/创建/分享/编辑/接收等明确行为记录",
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "available",
@@ -60,48 +56,58 @@
             "只按主题找内容本身时用 aisearch enterprise",
             "没有行为动作词时不要选用本工具"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "只按主题找内容本身时用 aisearch enterprise",
                 "没有行为动作词时不要选用本工具"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "risk-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "not_required",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "not_required",
               "source": "risk-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "command-verb",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "read",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "read",
               "source": "command-verb",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -110,50 +116,52 @@
             "dws aisearch behavior --types mail --behavior-type send --direction \"我-\u003e汐峰\" --format json",
             "dws aisearch behavior --queries \"智能化方案\" --types document --behavior-type create --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws aisearch behavior --types mail --behavior-type send --direction \"我-\u003e汐峰\" --format json",
                 "dws aisearch behavior --queries \"智能化方案\" --types document --behavior-type create --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "idempotent",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "idempotent",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "interface_mode": {
           "value": "mcp",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed",
           "candidates": [
             {
               "value": "mcp",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "mcp",
@@ -165,52 +173,61 @@
         },
         "interface_ref": {
           "value": "aisearch.search_enterprise_behavior",
-          "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise_behavior.interface_ref",
-          "precedence": "mcp_fallback",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "aisearch.search_enterprise_behavior",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "aisearch.search_enterprise_behavior",
               "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise_behavior.interface_ref",
               "precedence": "mcp_fallback",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "value": false,
+              "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise_behavior",
+              "precedence": "mcp_fallback",
+              "selected": false
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "low",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "low",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -218,19 +235,17 @@
           "value": [
             "用户明确问我/某人发过、发给、收到、创建、分享、编辑过什么"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "用户明确问我/某人发过、发给、收到、创建、分享、编辑过什么"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -244,13 +259,8 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "Cobra help: dws aisearch behavior --help",
-        "internal/cli/schema_command_registry.json",
-        "internal/cli/schema_command_registry.json#aisearch.search_enterprise_behavior",
-        "internal/cli/schema_hints/metadata/aisearch.json",
-        "internal/cli/schema_hints/selection/aisearch.json",
+        "corecmd.SchemaDecl",
         "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise_behavior",
-        "live-dws-schema:aisearch.search_enterprise_behavior",
         "skills/mono/references/intent-guide.md",
         "skills/mono/references/products/aisearch.md"
       ],
@@ -260,7 +270,7 @@
     },
     "aisearch enterprise": {
       "agent_summary": "搜索企业内部知识与相关内容（文档/IM/日历/待办/纪要/日志/邮件等）",
-      "agent_summary_source": "dws-agent-selection/aisearch",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "问“我发给谁/谁发给我/我创建过”等行为追溯时用 aisearch behavior",
@@ -269,7 +279,7 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws aisearch enterprise --queries \"智能化方案\" --types document --format json",
         "dws aisearch enterprise --queries \"OKR\" --types mail --time-range \"最近\" --format json"
@@ -277,33 +287,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "搜索企业内部知识与相关内容（文档/IM/日历/待办/纪要/日志/邮件等）",
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "搜索企业内部知识与相关内容（文档/IM/日历/待办/纪要/日志/邮件等）",
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input.",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "available",
@@ -319,10 +325,9 @@
             "企业找人时用 aisearch person",
             "已知具体资源 ID 要读写时改用对应产品命令"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
@@ -330,26 +335,23 @@
                 "企业找人时用 aisearch person",
                 "已知具体资源 ID 要读写时改用对应产品命令"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input.",
           "candidates": [
             {
               "value": "not_required",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "not_required",
@@ -361,15 +363,21 @@
         },
         "effect": {
           "value": "read",
-          "source": "command-verb",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "read",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "read",
               "source": "command-verb",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -378,50 +386,52 @@
             "dws aisearch enterprise --queries \"智能化方案\" --types document --format json",
             "dws aisearch enterprise --queries \"OKR\" --types mail --time-range \"最近\" --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws aisearch enterprise --queries \"智能化方案\" --types document --format json",
                 "dws aisearch enterprise --queries \"OKR\" --types mail --time-range \"最近\" --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "idempotent",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "idempotent",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "interface_mode": {
           "value": "mcp",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input.",
           "candidates": [
             {
               "value": "mcp",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "mcp",
@@ -433,52 +443,62 @@
         },
         "interface_ref": {
           "value": "aisearch.search_enterprise",
-          "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise.interface_ref",
-          "precedence": "mcp_fallback",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "aisearch.search_enterprise",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "aisearch.search_enterprise",
               "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise.interface_ref",
               "precedence": "mcp_fallback",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input.",
           "candidates": [
+            {
+              "value": true,
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": true,
               "source": "internal/cli/schema_hints/metadata/aisearch.json",
               "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input."
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
               "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input."
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "low",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "low",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -487,20 +507,18 @@
             "按主题找资料、方案、文档、消息、邮件等内容，且关注“有什么内容”",
             "用户显式给出时间词或类型词时分别映射到 --time-range / --types"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "按主题找资料、方案、文档、消息、邮件等内容，且关注“有什么内容”",
                 "用户显式给出时间词或类型词时分别映射到 --time-range / --types"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -514,13 +532,9 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "Cobra help: dws aisearch enterprise --help",
-        "internal/cli/schema_command_registry.json",
-        "internal/cli/schema_command_registry.json#aisearch.search_enterprise",
+        "corecmd.SchemaDecl",
         "internal/cli/schema_hints/metadata/aisearch.json",
-        "internal/cli/schema_hints/selection/aisearch.json",
         "internal/cli/schema_mcp_metadata.json#tools.aisearch.search_enterprise",
-        "live-dws-schema:aisearch.search_enterprise",
         "skills/mono/references/intent-guide.md",
         "skills/mono/references/products/aisearch.md"
       ],
@@ -531,7 +545,7 @@
     },
     "aisearch person": {
       "agent_summary": "企业内找人：按姓名/部门/职位/职责/上下级/手机号/工号筛选",
-      "agent_summary_source": "dws-agent-selection/aisearch",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "已有 userId 只需详情时用 contact user get",
@@ -540,7 +554,7 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws aisearch person --keyword \"张三\" --dimension name --format json",
         "dws aisearch person --keyword \"五道\" --dimension supervisor --format json"
@@ -548,33 +562,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "企业内找人：按姓名/部门/职位/职责/上下级/手机号/工号筛选",
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "企业内找人：按姓名/部门/职位/职责/上下级/手机号/工号筛选",
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "available",
@@ -590,10 +600,9 @@
             "精确通讯录关键词搜同事/好友且不涉及职责语义时可用 contact user search",
             "搜企业知识内容时用 aisearch enterprise；搜行为记录时用 aisearch behavior"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
@@ -601,38 +610,49 @@
                 "精确通讯录关键词搜同事/好友且不涉及职责语义时可用 contact user search",
                 "搜企业知识内容时用 aisearch enterprise；搜行为记录时用 aisearch behavior"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "risk-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "not_required",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "not_required",
               "source": "risk-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "command-verb",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "read",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "read",
               "source": "command-verb",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -641,50 +661,52 @@
             "dws aisearch person --keyword \"张三\" --dimension name --format json",
             "dws aisearch person --keyword \"五道\" --dimension supervisor --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws aisearch person --keyword \"张三\" --dimension name --format json",
                 "dws aisearch person --keyword \"五道\" --dimension supervisor --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "idempotent",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "idempotent",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "interface_mode": {
           "value": "mcp",
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed",
           "candidates": [
             {
               "value": "mcp",
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "mcp",
@@ -696,52 +718,61 @@
         },
         "interface_ref": {
           "value": "aisearch.enterprise_person_search",
-          "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.enterprise_person_search.interface_ref",
-          "precedence": "mcp_fallback",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "aisearch.enterprise_person_search",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "aisearch.enterprise_person_search",
               "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.enterprise_person_search.interface_ref",
               "precedence": "mcp_fallback",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/aisearch marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "value": false,
+              "source": "internal/cli/schema_mcp_metadata.json#tools.aisearch.enterprise_person_search",
+              "precedence": "mcp_fallback",
+              "selected": false
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "low",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "low",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -750,20 +781,18 @@
             "找人、谁负责某事、查上级/下级、按手机号或工号定位人员",
             "需要把维度词映射到 --dimension，关键词只保留目标实体"
           ],
-          "source": "internal/cli/schema_hints/selection/aisearch.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "找人、谁负责某事、查上级/下级、按手机号或工号定位人员",
                 "需要把维度词映射到 --dimension，关键词只保留目标实体"
               ],
-              "source": "internal/cli/schema_hints/selection/aisearch.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -777,13 +806,8 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "Cobra help: dws aisearch person --help",
-        "internal/cli/schema_command_registry.json",
-        "internal/cli/schema_command_registry.json#aisearch.enterprise_person_search",
-        "internal/cli/schema_hints/metadata/aisearch.json",
-        "internal/cli/schema_hints/selection/aisearch.json",
+        "corecmd.SchemaDecl",
         "internal/cli/schema_mcp_metadata.json#tools.aisearch.enterprise_person_search",
-        "live-dws-schema:aisearch.enterprise_person_search",
         "skills/mono/references/intent-guide.md",
         "skills/mono/references/products/aisearch.md",
         "skills/mono/references/products/mail.md"

internal/cli/schema_agent_metadata/audit.json

@@ -3,7 +3,7 @@
   "tools": {
     "audit export": {
       "agent_summary": "按日期范围导出本地操作审计日志（jsonl 或 csv）",
-      "agent_summary_source": "dws-agent-selection/audit",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "只看最近几条用 audit tail",
@@ -11,7 +11,7 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws audit export --format jsonl",
         "dws audit export --since 2026-07-01 --until 2026-07-14 --format csv"
@@ -19,33 +19,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "按日期范围导出本地操作审计日志（jsonl 或 csv）",
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。",
           "candidates": [
             {
               "value": "按日期范围导出本地操作审计日志（jsonl 或 csv）",
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -54,52 +50,46 @@
             "只看最近几条用 audit tail",
             "只校验哈希链完整性用 audit verify"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "只看最近几条用 audit tail",
                 "只校验哈希链完整性用 audit verify"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "not_required",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "read",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -108,82 +98,74 @@
             "dws audit export --format jsonl",
             "dws audit export --since 2026-07-01 --until 2026-07-14 --format csv"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws audit export --format jsonl",
                 "dws audit export --since 2026-07-01 --until 2026-07-14 --format csv"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "idempotent",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_mode": {
           "value": "local",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "local",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_reason": {
           "value": "命令读取并导出本地审计日志文件，不绑定 pinned MCP RPC",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "命令读取并导出本地审计日志文件，不绑定 pinned MCP RPC",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_ref": {
           "value": null,
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "interface_disposition_matrix",
           "review_reason": "final interface mode local forbids a direct MCP interface_ref",
           "candidates": [
             {
               "value": null,
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true,
               "review_reason": "final interface mode local forbids a direct MCP interface_ref"
             }
@@ -191,40 +173,29 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log export from #555; no remote RPC.",
           "candidates": [
             {
               "value": "low",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log export from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -232,19 +203,17 @@
           "value": [
             "需要把本地审计日志导出为 jsonl/csv，或按 --since/--until 取一段时间"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "需要把本地审计日志导出为 jsonl/csv，或按 --since/--until 取一段时间"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读导出，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -255,11 +224,7 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "cobra-help:dws audit export --help",
-        "internal/app/audit_command.go",
-        "internal/cli/schema_command_registry.json#audit.export",
-        "internal/cli/schema_hints/metadata/audit.json",
-        "internal/cli/schema_hints/selection/audit.json"
+        "corecmd.SchemaDecl"
       ],
       "use_when": [
         "需要把本地审计日志导出为 jsonl/csv，或按 --since/--until 取一段时间"
@@ -267,7 +232,7 @@
     },
     "audit tail": {
       "agent_summary": "查看本地操作审计日志最近 N 条记录",
-      "agent_summary_source": "dws-agent-selection/audit",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "需要按日期范围整段导出用 audit export",
@@ -275,7 +240,7 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws audit tail",
         "dws audit tail --lines 50"
@@ -283,33 +248,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "查看本地操作审计日志最近 N 条记录",
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。",
           "candidates": [
             {
               "value": "查看本地操作审计日志最近 N 条记录",
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -318,52 +279,46 @@
             "需要按日期范围整段导出用 audit export",
             "需要校验哈希链用 audit verify"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "需要按日期范围整段导出用 audit export",
                 "需要校验哈希链用 audit verify"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "not_required",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "read",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -372,82 +327,74 @@
             "dws audit tail",
             "dws audit tail --lines 50"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws audit tail",
                 "dws audit tail --lines 50"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "idempotent",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_mode": {
           "value": "local",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "local",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_reason": {
           "value": "命令读取本地审计日志尾部，不绑定 pinned MCP RPC",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "命令读取本地审计日志尾部，不绑定 pinned MCP RPC",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_ref": {
           "value": null,
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "interface_disposition_matrix",
           "review_reason": "final interface mode local forbids a direct MCP interface_ref",
           "candidates": [
             {
               "value": null,
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true,
               "review_reason": "final interface mode local forbids a direct MCP interface_ref"
             }
@@ -455,40 +402,29 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit log tail from #555; no remote RPC.",
           "candidates": [
             {
               "value": "low",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit log tail from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -496,19 +432,17 @@
           "value": [
             "需要快速查看最近写入的审计记录（默认最近 20 条）"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "需要快速查看最近写入的审计记录（默认最近 20 条）"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读查看，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -519,11 +453,7 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "cobra-help:dws audit tail --help",
-        "internal/app/audit_command.go",
-        "internal/cli/schema_command_registry.json#audit.tail",
-        "internal/cli/schema_hints/metadata/audit.json",
-        "internal/cli/schema_hints/selection/audit.json"
+        "corecmd.SchemaDecl"
       ],
       "use_when": [
         "需要快速查看最近写入的审计记录（默认最近 20 条）"
@@ -531,14 +461,14 @@
     },
     "audit verify": {
       "agent_summary": "校验本地审计日志文件的哈希链完整性",
-      "agent_summary_source": "dws-agent-selection/audit",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "只浏览或导出日志内容时用 audit tail / audit export"
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws audit verify",
         "dws audit verify --file /path/to/audit.jsonl"
@@ -546,33 +476,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "校验本地审计日志文件的哈希链完整性",
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。",
           "candidates": [
             {
               "value": "校验本地审计日志文件的哈希链完整性",
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -580,51 +506,45 @@
           "value": [
             "只浏览或导出日志内容时用 audit tail / audit export"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "只浏览或导出日志内容时用 audit tail / audit export"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "not_required",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "read",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -633,82 +553,74 @@
             "dws audit verify",
             "dws audit verify --file /path/to/audit.jsonl"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws audit verify",
                 "dws audit verify --file /path/to/audit.jsonl"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "idempotent",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_mode": {
           "value": "local",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "local",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_reason": {
           "value": "命令校验本地审计日志哈希链，不绑定 pinned MCP RPC",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "命令校验本地审计日志哈希链，不绑定 pinned MCP RPC",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_ref": {
           "value": null,
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "interface_disposition_matrix",
           "review_reason": "final interface mode local forbids a direct MCP interface_ref",
           "candidates": [
             {
               "value": null,
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true,
               "review_reason": "final interface mode local forbids a direct MCP interface_ref"
             }
@@ -716,40 +628,29 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "internal/cli/schema_hints/metadata/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Local audit hash-chain verify from #555; no remote RPC.",
           "candidates": [
             {
               "value": "low",
-              "source": "internal/cli/schema_hints/metadata/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Local audit hash-chain verify from #555; no remote RPC."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -757,19 +658,17 @@
           "value": [
             "怀疑审计文件被篡改，或需要确认最新/指定文件哈希链是否完整"
           ],
-          "source": "internal/cli/schema_hints/selection/audit.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "怀疑审计文件被篡改，或需要确认最新/指定文件哈希链是否完整"
               ],
-              "source": "internal/cli/schema_hints/selection/audit.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "纳入 #555 公开 audit leaf 的 Agent 选型文案；本地只读校验，示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -780,11 +679,7 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "cobra-help:dws audit verify --help",
-        "internal/app/audit_command.go",
-        "internal/cli/schema_command_registry.json#audit.verify",
-        "internal/cli/schema_hints/metadata/audit.json",
-        "internal/cli/schema_hints/selection/audit.json"
+        "corecmd.SchemaDecl"
       ],
       "use_when": [
         "怀疑审计文件被篡改，或需要确认最新/指定文件哈希链是否完整"

internal/cli/schema_agent_metadata/devdoc.json

@@ -3,7 +3,7 @@
   "tools": {
     "devdoc article search": {
       "agent_summary": "搜索钉钉开放平台开发文档，返回资料与链接（不生成分析答案）",
-      "agent_summary_source": "dws-agent-selection/devdoc",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "搜索用户业务文档用 drive/wiki/doc，不要用 devdoc",
@@ -11,7 +11,7 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws devdoc article search --query \"OAuth2 接入\" --format json",
         "dws devdoc article search --query \"errcode 40078\" --format json"
@@ -19,33 +19,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "搜索钉钉开放平台开发文档，返回资料与链接（不生成分析答案）",
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "搜索钉钉开放平台开发文档，返回资料与链接（不生成分析答案）",
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "available",
@@ -60,36 +56,32 @@
             "搜索用户业务文档用 drive/wiki/doc，不要用 devdoc",
             "要执行开放平台应用配置变更时用 dev"
           ],
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "搜索用户业务文档用 drive/wiki/doc，不要用 devdoc",
                 "要执行开放平台应用配置变更时用 dev"
               ],
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
           "candidates": [
             {
               "value": "not_required",
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "not_required",
@@ -101,15 +93,21 @@
         },
         "effect": {
           "value": "read",
-          "source": "command-verb",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "read",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "read",
               "source": "command-verb",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -118,50 +116,52 @@
             "dws devdoc article search --query \"OAuth2 接入\" --format json",
             "dws devdoc article search --query \"errcode 40078\" --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws devdoc article search --query \"OAuth2 接入\" --format json",
                 "dws devdoc article search --query \"errcode 40078\" --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "idempotent",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "idempotent",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "interface_mode": {
           "value": "mcp",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
           "candidates": [
             {
               "value": "mcp",
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "mcp",
@@ -173,15 +173,21 @@
         },
         "interface_ref": {
           "value": "devdoc.search_open_platform_docs",
-          "source": "internal/cli/schema_hints/imported/wukong.json",
-          "precedence": "imported",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "devdoc.search_open_platform_docs",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "devdoc.search_open_platform_docs",
               "source": "internal/cli/schema_hints/imported/wukong.json",
               "precedence": "imported",
-              "selected": true
+              "selected": false
             },
             {
               "value": "devdoc.search_open_platform_docs",
@@ -193,38 +199,42 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
           "candidates": [
+            {
+              "value": true,
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": true,
               "source": "internal/cli/schema_hints/metadata/devdoc.json",
               "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword."
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
-              "precedence": "reviewed_explicit",
               "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword."
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "low",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "low",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
@@ -232,19 +242,17 @@
           "value": [
             "查 OpenAPI、字段、错误码、OAuth2、接入指南等开放平台开发问题"
           ],
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "查 OpenAPI、字段、错误码、OAuth2、接入指南等开放平台开发问题"
               ],
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -258,20 +266,13 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "CommandRegistry:canonical_path=devdoc.search_open_platform_docs_rag",
-        "Skill:skills/mono/references/products/devdoc.md",
-        "cobra-help:dws devdoc article search",
+        "corecmd.SchemaDecl",
         "dws-wukong-envelope@4574f7022c32:dws-wukong-discovery.devdoc.prod.json#devdoc.search_open_platform_docs",
-        "internal/cli/schema_command_registry.json#devdoc.search_open_platform_docs_rag",
         "internal/cli/schema_hints/imported/wukong.json",
         "internal/cli/schema_hints/metadata/devdoc.json",
-        "internal/cli/schema_hints/selection/devdoc.json",
         "internal/cli/schema_mcp_metadata.json#tools.devdoc.search_open_platform_docs_rag",
-        "live-dws-schema:devdoc.search_open_platform_docs_rag",
         "skills/mono/references/products/devdoc.md",
-        "skills/mono/references/products/simple.md",
-        "structured-hint:internal/cli/schema_hints/imported/wukong.json#devdoc.search_open_platform_docs_rag",
-        "structured-hint:internal/cli/schema_hints/selection-review.json#devdoc.search_open_platform_docs_rag"
+        "skills/mono/references/products/simple.md"
       ],
       "use_when": [
         "查 OpenAPI、字段、错误码、OAuth2、接入指南等开放平台开发问题"

internal/cli/schema_agent_metadata/index.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "source_hash": "sha256:670ca810a83bf2aa6f387a18c3af746393d5ea9de24570cbcebbcf994eb7b613",
+  "source_hash": "sha256:dc81f9a6bf1c4137d03f3b0aa7d2b17fcd72c5defdfc10ad26ee4911c4257098",
   "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
   "coverage": {
     "surface_products": 26,
@@ -12,8 +12,8 @@
     "tools_with_avoid_when": 845,
     "tools_with_examples": 845,
     "tools_with_interface_mode": 845,
-    "unmatched_skill_tools": 122,
-    "unreviewed_skill_tools": 11
+    "unmatched_skill_tools": 118,
+    "unreviewed_skill_tools": 7
   },
   "products": {
     "aisearch": {

internal/cli/schema_agent_metadata/live.json

@@ -3,47 +3,43 @@
   "tools": {
     "live stream list": {
       "agent_summary": "查看当前用户发起的直播列表与基础统计",
-      "agent_summary_source": "dws-agent-selection/live",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "需要创建/开播/结束直播时不要使用；当前公开面仅列表查询"
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws live stream list"
       ],
       "field_provenance": {
         "agent_summary": {
           "value": "查看当前用户发起的直播列表与基础统计",
-          "source": "internal/cli/schema_hints/selection/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "查看当前用户发起的直播列表与基础统计",
-              "source": "internal/cli/schema_hints/selection/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/live marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "available",
@@ -57,46 +53,44 @@
           "value": [
             "需要创建/开播/结束直播时不要使用；当前公开面仅列表查询"
           ],
-          "source": "internal/cli/schema_hints/selection/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "需要创建/开播/结束直播时不要使用；当前公开面仅列表查询"
               ],
-              "source": "internal/cli/schema_hints/selection/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "risk-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
             {
               "value": "not_required",
-              "source": "risk-default",
-              "precedence": "inference_or_default",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "command-verb",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
             {
               "value": "read",
-              "source": "command-verb",
-              "precedence": "inference_or_default",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true
             }
           ]
@@ -105,49 +99,45 @@
           "value": [
             "dws live stream list"
           ],
-          "source": "internal/cli/schema_hints/selection/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws live stream list"
               ],
-              "source": "internal/cli/schema_hints/selection/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
             {
               "value": "idempotent",
-              "source": "effect-default",
-              "precedence": "inference_or_default",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true
             }
           ]
         },
         "interface_mode": {
           "value": "mcp",
-          "source": "internal/cli/schema_hints/metadata/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
           "candidates": [
             {
               "value": "mcp",
-              "source": "internal/cli/schema_hints/metadata/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/live marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "mcp",
@@ -159,15 +149,21 @@
         },
         "interface_ref": {
           "value": "live.get_my_lives",
-          "source": "internal/cli/schema_hints/imported/wukong.json",
-          "precedence": "imported",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "live.get_my_lives",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "live.get_my_lives",
               "source": "internal/cli/schema_hints/imported/wukong.json",
               "precedence": "imported",
-              "selected": true
+              "selected": false
             },
             {
               "value": "live.get_my_lives",
@@ -179,37 +175,28 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/live marks this tool as reviewed"
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "risk": {
           "value": "low",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
             {
               "value": "low",
-              "source": "effect-default",
-              "precedence": "inference_or_default",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true
             }
           ]
@@ -218,19 +205,17 @@
           "value": [
             "用户要看自己发起过的直播、状态或观看量等列表信息"
           ],
-          "source": "internal/cli/schema_hints/selection/live.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "用户要看自己发起过的直播、状态或观看量等列表信息"
               ],
-              "source": "internal/cli/schema_hints/selection/live.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -244,19 +229,10 @@
       "reviewed": true,
       "risk": "low",
       "source_refs": [
-        "CommandRegistry:canonical_path=live.get_my_lives",
-        "Skill:skills/multi/dingtalk-live/SKILL.md",
-        "cobra-help:dws live stream list",
+        "corecmd.SchemaDecl",
         "dws-wukong-envelope@4574f7022c32:dws-wukong-discovery.live.prod.json#live.get_my_lives",
-        "internal/cli/schema_command_registry.json#live.get_my_lives",
         "internal/cli/schema_hints/imported/wukong.json",
-        "internal/cli/schema_hints/metadata/live.json",
-        "internal/cli/schema_hints/selection/live.json",
-        "internal/cli/schema_mcp_metadata.json#tools.live.get_my_lives",
-        "live-dws-schema:live.get_my_lives",
-        "skills/mono/references/products/live.md",
-        "structured-hint:internal/cli/schema_hints/imported/wukong.json#live.get_my_lives",
-        "structured-hint:internal/cli/schema_hints/selection-review.json#live.get_my_lives"
+        "internal/cli/schema_mcp_metadata.json#tools.live.get_my_lives"
       ],
       "use_when": [
         "用户要看自己发起过的直播、状态或观看量等列表信息"

internal/cli/schema_agent_metadata/mcp.json

@@ -3,7 +3,7 @@
   "tools": {
     "mcp url get": {
       "agent_summary": "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
-      "agent_summary_source": "dws-agent-selection/mcp",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "只是查询 DWS 已公开命令或参数时使用 dws schema",
@@ -11,40 +11,36 @@
       ],
       "confirmation": "not_required",
       "effect": "read",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws mcp url get 10043 --format json"
       ],
       "field_provenance": {
         "agent_summary": {
           "value": "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
-          "source": "internal/cli/schema_hints/selection/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
           "candidates": [
             {
               "value": "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
-              "source": "internal/cli/schema_hints/selection/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -53,52 +49,46 @@
             "只是查询 DWS 已公开命令或参数时使用 dws schema",
             "用户要求把返回的凭据 URL 发送到群聊、文档、邮件、日志或代码仓库时不要执行或传播"
           ],
-          "source": "internal/cli/schema_hints/selection/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
           "candidates": [
             {
               "value": [
                 "只是查询 DWS 已公开命令或参数时使用 dws schema",
                 "用户要求把返回的凭据 URL 发送到群聊、文档、邮件、日志或代码仓库时不要执行或传播"
               ],
-              "source": "internal/cli/schema_hints/selection/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "not_required",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "effect": {
           "value": "read",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "read",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -106,81 +96,73 @@
           "value": [
             "dws mcp url get 10043 --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
           "candidates": [
             {
               "value": [
                 "dws mcp url get 10043 --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "idempotent",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "idempotent",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_mode": {
           "value": "composite",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "composite",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_reason": {
           "value": "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata.",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_ref": {
           "value": null,
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "interface_disposition_matrix",
           "review_reason": "final interface mode composite forbids a direct MCP interface_ref",
           "candidates": [
             {
               "value": null,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true,
               "review_reason": "final interface mode composite forbids a direct MCP interface_ref"
             }
@@ -188,40 +170,29 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "risk": {
           "value": "medium",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
           "candidates": [
             {
               "value": "medium",
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output."
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -229,19 +200,17 @@
           "value": [
             "已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"
           ],
-          "source": "internal/cli/schema_hints/selection/mcp.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
           "candidates": [
             {
               "value": [
                 "已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"
               ],
-              "source": "internal/cli/schema_hints/selection/mcp.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -252,12 +221,7 @@
       "reviewed": true,
       "risk": "medium",
       "source_refs": [
-        "cobra-help:dws mcp url get --help",
-        "internal/app/mcp_url_command.go",
-        "internal/cli/schema_command_registry.json#mcp.url_get",
-        "internal/cli/schema_hints/metadata/mcp.json",
-        "internal/cli/schema_hints/selection/mcp.json",
-        "pkg/edition/default.go#openSupplementServers"
+        "corecmd.SchemaDecl"
       ],
       "use_when": [
         "已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"

internal/cli/schema_agent_metadata/pat.json

@@ -3,14 +3,14 @@
   "tools": {
     "pat browser-policy": {
       "agent_summary": "配置 PAT 授权流程是否允许打开本地浏览器",
-      "agent_summary_source": "dws-agent-selection/pat",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "需要授予产品 scope 时用 pat chmod，而不是改浏览器策略"
       ],
       "confirmation": "not_required",
       "effect": "write",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws pat browser-policy --enabled --format json",
         "dws pat browser-policy --enabled=false --agentCode \u003cAGENT_CODE\u003e --format json"
@@ -18,33 +18,29 @@
       "field_provenance": {
         "agent_summary": {
           "value": "配置 PAT 授权流程是否允许打开本地浏览器",
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "配置 PAT 授权流程是否允许打开本地浏览器",
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
@@ -52,49 +48,51 @@
           "value": [
             "需要授予产品 scope 时用 pat chmod，而不是改浏览器策略"
           ],
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "需要授予产品 scope 时用 pat chmod，而不是改浏览器策略"
               ],
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "not_required",
-          "source": "risk-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "not_required",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "not_required",
               "source": "risk-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "effect": {
           "value": "write",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "write",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "write",
@@ -109,80 +107,80 @@
             "dws pat browser-policy --enabled --format json",
             "dws pat browser-policy --enabled=false --agentCode \u003cAGENT_CODE\u003e --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws pat browser-policy --enabled --format json",
                 "dws pat browser-policy --enabled=false --agentCode \u003cAGENT_CODE\u003e --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "unknown",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "unknown",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "unknown",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "interface_mode": {
           "value": "local",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "local",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_reason": {
           "value": "命令仅操作本地进程或策略文件，不调用 MCP 接口",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "命令仅操作本地进程或策略文件，不调用 MCP 接口",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "interface_ref": {
           "value": null,
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "interface_disposition_matrix",
           "review_reason": "final interface mode local forbids a direct MCP interface_ref",
           "candidates": [
             {
               "value": null,
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
               "selected": true,
               "review_reason": "final interface mode local forbids a direct MCP interface_ref"
             }
@@ -190,40 +188,29 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
-            },
-            {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "risk": {
           "value": "medium",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "medium",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "medium",
@@ -237,19 +224,17 @@
           "value": [
             "需要允许或禁止某 Agent 在 PAT 授权时打开浏览器"
           ],
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "需要允许或禁止某 Agent 在 PAT 授权时打开浏览器"
               ],
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -260,15 +245,8 @@
       "reviewed": true,
       "risk": "medium",
       "source_refs": [
-        "CommandRegistry:canonical_path=pat.browser_policy",
-        "Skill:skills/mono/references/products/pat.md",
-        "cobra-help:dws pat browser-policy",
-        "internal/cli/schema_command_registry.json#pat.browser_policy",
-        "internal/cli/schema_hints/metadata/pat.json",
-        "internal/cli/schema_hints/selection/pat.json",
-        "live-dws-schema:pat.browser_policy#FAILED",
-        "skills/mono/references/products/pat.md",
-        "structured-hint:internal/cli/schema_hints/selection-review.json#pat.browser_policy"
+        "corecmd.SchemaDecl",
+        "skills/mono/references/products/pat.md"
       ],
       "use_when": [
         "需要允许或禁止某 Agent 在 PAT 授权时打开浏览器"
@@ -276,7 +254,7 @@
     },
     "pat chmod": {
       "agent_summary": "预览或执行 PAT 批量行为授权（支持 dryRun / pending flow）",
-      "agent_summary_source": "dws-agent-selection/pat",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "普通 OAuth 登录用 auth，不要用 pat",
@@ -285,40 +263,36 @@
       ],
       "confirmation": "user_required",
       "effect": "write",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws pat chmod --products calendar,aitable --grant-type session --session-id \u003cSESSION_ID\u003e --dry-run --format json"
       ],
       "field_provenance": {
         "agent_summary": {
           "value": "预览或执行 PAT 批量行为授权（支持 dryRun / pending flow）",
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": "预览或执行 PAT 批量行为授权（支持 dryRun / pending flow）",
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "availability": {
           "value": "available",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "available",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "available",
@@ -334,10 +308,9 @@
             "授权产品、grant-type 或 session-id 未明确时不要执行写入",
             "只要改本地浏览器打开策略时用 pat browser-policy"
           ],
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
@@ -345,26 +318,23 @@
                 "授权产品、grant-type 或 session-id 未明确时不要执行写入",
                 "只要改本地浏览器打开策略时用 pat browser-policy"
               ],
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "confirmation": {
           "value": "user_required",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "user_required",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "user_required",
@@ -377,17 +347,15 @@
         },
         "effect": {
           "value": "write",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "write",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "write",
@@ -408,49 +376,51 @@
           "value": [
             "dws pat chmod --products calendar,aitable --grant-type session --session-id \u003cSESSION_ID\u003e --dry-run --format json"
           ],
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "dws pat chmod --products calendar,aitable --grant-type session --session-id \u003cSESSION_ID\u003e --dry-run --format json"
               ],
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         },
         "idempotency": {
           "value": "unknown",
-          "source": "effect-default",
-          "precedence": "inference_or_default",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
           "candidates": [
+            {
+              "value": "unknown",
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
+            },
             {
               "value": "unknown",
               "source": "effect-default",
               "precedence": "inference_or_default",
-              "selected": true
+              "selected": false
             }
           ]
         },
         "interface_mode": {
           "value": "mcp",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "mcp",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "mcp",
@@ -462,17 +432,15 @@
         },
         "interface_ref": {
           "value": "pat.pat.batch_grant",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "pat.pat.batch_grant",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "pat.pat.batch_grant",
@@ -484,40 +452,35 @@
         },
         "reviewed": {
           "value": true,
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": true,
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
-              "value": true,
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": false,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "value": false,
+              "source": "internal/cli/schema_mcp_metadata.json#tools.pat.batch_grant",
+              "precedence": "mcp_fallback",
+              "selected": false
             }
           ]
         },
         "risk": {
           "value": "high",
-          "source": "internal/cli/schema_hints/metadata/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/pat marks this tool as reviewed",
           "candidates": [
             {
               "value": "high",
-              "source": "internal/cli/schema_hints/metadata/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "dws-tool-metadata/pat marks this tool as reviewed"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             },
             {
               "value": "high",
@@ -533,20 +496,18 @@
             "命令提示缺少行为授权，需要按产品或 scope 批量授权",
             "先 --dry-run 查看 selected/skipped/pending，用户确认后再执行"
           ],
-          "source": "internal/cli/schema_hints/selection/pat.json",
-          "precedence": "reviewed_explicit",
+          "source": "corecmd.contract",
+          "precedence": "contract_final",
           "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
           "candidates": [
             {
               "value": [
                 "命令提示缺少行为授权，需要按产品或 scope 批量授权",
                 "先 --dry-run 查看 selected/skipped/pending，用户确认后再执行"
               ],
-              "source": "internal/cli/schema_hints/selection/pat.json",
-              "precedence": "reviewed_explicit",
-              "selected": true,
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。"
+              "source": "corecmd.contract",
+              "precedence": "contract_final",
+              "selected": true
             }
           ]
         }
@@ -560,18 +521,9 @@
       "reviewed": true,
       "risk": "high",
       "source_refs": [
-        "CommandRegistry:canonical_path=pat.batch_grant",
-        "Skill:skills/mono/references/products/pat.md",
-        "cobra-help:dws pat chmod",
-        "helper:internal/pat/chmod.go#typed_yes",
-        "internal/cli/schema_command_registry.json#pat.batch_grant",
-        "internal/cli/schema_hints/metadata/pat.json",
-        "internal/cli/schema_hints/selection/pat.json",
+        "corecmd.SchemaDecl",
         "internal/cli/schema_mcp_metadata.json#tools.pat.batch_grant",
-        "live-dws-schema:pat.batch_grant#FAILED",
-        "pinned-mcp:pat.batch_grant",
-        "skills/mono/references/products/pat.md",
-        "structured-hint:internal/cli/schema_hints/selection-review.json#pat.batch_grant"
+        "skills/mono/references/products/pat.md"
       ],
       "use_when": [
         "命令提示缺少行为授权，需要按产品或 scope 批量授权",

internal/cli/schema_agent_metadata_audit.json

@@ -1,11 +1,11 @@
 {
   "version": 1,
-  "source_hash": "sha256:670ca810a83bf2aa6f387a18c3af746393d5ea9de24570cbcebbcf994eb7b613",
+  "source_hash": "sha256:dc81f9a6bf1c4137d03f3b0aa7d2b17fcd72c5defdfc10ad26ee4911c4257098",
   "surface_hash": "sha256:60eee8e2f37d6d9d60689efce85082798eb9ad38b7ba7c0b471c3de676a85a16",
   "source_files": 160,
   "hint_files": 54,
   "hint_products": 43,
-  "hint_tools": 1842,
+  "hint_tools": 221,
   "interface_metadata": {
     "source": "mcp-tools-list+cli-registry",
     "revision": "4574f7022c32cf4c033e9b7b4156e2fec815fed8",
@@ -13,8 +13,8 @@
     "source_tools": 419,
     "surface_tools": 414,
     "eligible_summaries": 413,
-    "applied_summaries": 0,
-    "preserved_summaries": 413,
+    "applied_summaries": 268,
+    "preserved_summaries": 145,
     "rejected_tools": [
       "chat.unread_message_conversation_list"
     ],
@@ -36,8 +36,8 @@
     "tools_with_avoid_when": 845,
     "tools_with_examples": 845,
     "tools_with_interface_mode": 845,
-    "unmatched_skill_tools": 122,
-    "unreviewed_skill_tools": 11
+    "unmatched_skill_tools": 118,
+    "unreviewed_skill_tools": 7
   },
   "source_products": [
     "agoal",
@@ -91,18 +91,6 @@
     {
       "tool_path": "chat.get_group_members"
     },
-    {
-      "tool_path": "devdoc.devdoc_rag_pretest"
-    },
-    {
-      "tool_path": "devdoc.search_dingtalk_open_docs"
-    },
-    {
-      "tool_path": "devdoc.search_open_error_code_rag"
-    },
-    {
-      "tool_path": "devdoc.search_open_platform_docs"
-    },
     {
       "tool_path": "doc",
       "candidates": [

internal/cli/schema_agent_selection.go

@@ -20,6 +20,8 @@ import (
 	"fmt"
 	"sort"
 	"strings"
+
+	"github.com/spf13/cobra"
 )
 
 var marshalManualAgentSelectionFixture = json.Marshal
@@ -71,17 +73,27 @@ func BuildManualAgentSelectionEvalFixture(bound BoundCommandRegistry, hints Manu
 	fixture := ManualAgentSelectionFixture{Version: manualAgentSelectionFixtureVersion}
 	report := ManualAgentSelectionReport{}
 	expectedTools := make(map[string]bool, len(bound.Commands))
+	declaredTools := map[string]bool{}
 	candidatesByProduct := map[string][]string{}
 	for _, command := range bound.Commands {
 		canonical := strings.TrimSpace(command.CanonicalPath)
 		expectedTools[canonical] = true
+		// Declared tools source selection assertions from the Contract final
+		// overlay (corecmd.SchemaDecl) instead of a hint-file row.
+		if HasRuntimeContractFinal(command.PrimaryCommand) {
+			declaredTools[canonical] = true
+		}
 		productID, _, ok := strings.Cut(canonical, ".")
 		if !ok || strings.TrimSpace(productID) == "" {
 			return fixture, report, fmt.Errorf("agent_hints selection has invalid bound canonical path %q", canonical)
 		}
 		candidatesByProduct[productID] = append(candidatesByProduct[productID], canonical)
 	}
-	if err := validateManualAgentHintExactSet("selection tools", expectedTools, mapKeysManualAgentTools(hints.Tools)); err != nil {
+	hintTools := mapKeysManualAgentTools(hints.Tools)
+	for canonical := range declaredTools {
+		hintTools[canonical] = true
+	}
+	if err := validateManualAgentHintExactSet("selection tools", expectedTools, hintTools); err != nil {
 		return fixture, report, err
 	}
 	for productID := range candidatesByProduct {
@@ -105,7 +117,10 @@ func BuildManualAgentSelectionEvalFixture(bound BoundCommandRegistry, hints Manu
 			return fixture, report, err
 		}
 
-		hint := hints.Tools[canonical]
+		hint, hintOK := hints.Tools[canonical]
+		if !hintOK && declaredTools[canonical] {
+			hint = contractFinalSelectionHint(command.PrimaryCommand)
+		}
 		if len(hint.UseWhen) == 0 {
 			return fixture, report, fmt.Errorf("agent_hints tool %s requires at least one positive use_when selection assertion", canonical)
 		}
@@ -169,6 +184,23 @@ func ValidateManualAgentSelectionContract(bound BoundCommandRegistry, hints Manu
 	return report, err
 }
 
+// contractFinalSelectionHint synthesizes the selection assertions of a
+// declared tool from its Contract final overlay, so declared tools keep full
+// semantic-eval coverage without a hint-file row.
+func contractFinalSelectionHint(command *cobra.Command) ManualAgentToolHint {
+	hint := ManualAgentToolHint{Reviewed: true, Revision: "contract", Reason: "Contract final declaration (corecmd.SchemaDecl)"}
+	payload, ok := RuntimeContractFinal(command)
+	if !ok || payload.Selection == nil {
+		return hint
+	}
+	selection := payload.Selection
+	hint.AgentSummary = selection.AgentSummary
+	hint.UseWhen = selection.UseWhen
+	hint.AvoidWhen = selection.AvoidWhen
+	hint.Examples = selection.Examples
+	return hint
+}
+
 func validateManualAgentSelectionBinding(bound BoundCommandRegistry, canonical string, command BoundCommandSpec) error {
 	if command.CanonicalPath != canonical {
 		return fmt.Errorf("agent_hints selection canonical %q resolves to mismatched BoundCommandRegistry entry %q", canonical, command.CanonicalPath)

internal/cli/schema_catalog/tools/devdoc.json

@@ -2,25 +2,12 @@
   "product": "devdoc",
   "tools": {
     "devdoc.search_open_platform_docs_rag": {
-      "agent_metadata_source": "embedded-skill-metadata",
+      "agent_metadata_source": "corecmd.contract",
       "agent_source_refs": [
-        "CommandRegistry:canonical_path=devdoc.search_open_platform_docs_rag",
-        "Skill:skills/mono/references/products/devdoc.md",
-        "cobra-help:dws devdoc article search",
-        "dws-wukong-envelope@4574f7022c32:dws-wukong-discovery.devdoc.prod.json#devdoc.search_open_platform_docs",
-        "internal/cli/schema_command_registry.json#devdoc.search_open_platform_docs_rag",
-        "internal/cli/schema_hints/imported/wukong.json",
-        "internal/cli/schema_hints/metadata/devdoc.json",
-        "internal/cli/schema_hints/selection/devdoc.json",
-        "internal/cli/schema_mcp_metadata.json#tools.devdoc.search_open_platform_docs_rag",
-        "live-dws-schema:devdoc.search_open_platform_docs_rag",
-        "skills/mono/references/products/devdoc.md",
-        "skills/mono/references/products/simple.md",
-        "structured-hint:internal/cli/schema_hints/imported/wukong.json#devdoc.search_open_platform_docs_rag",
-        "structured-hint:internal/cli/schema_hints/selection-review.json#devdoc.search_open_platform_docs_rag"
+        "corecmd.SchemaDecl"
       ],
       "agent_summary": "搜索钉钉开放平台开发文档，返回资料与链接（不生成分析答案）",
-      "agent_summary_source": "dws-agent-selection/devdoc",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "搜索用户业务文档用 drive/wiki/doc，不要用 devdoc",
@@ -41,7 +28,7 @@
       "description": "按关键词搜索 open.dingtalk.com 文档，支持分页。默认表格输出，可用 -f json 获取完整响应。",
       "display": "开放平台文档搜索",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws devdoc article search --query \"OAuth2 接入\" --format json",
         "dws devdoc article search --query \"errcode 40078\" --format json"
@@ -50,58 +37,58 @@
         "agent_summary": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "搜索钉钉开放平台开发文档，返回资料与链接（不生成分析答案）"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "搜索钉钉开放平台开发文档，返回资料与链接（不生成分析答案）"
         },
         "availability": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "value": "available"
-            },
-            {
-              "precedence": "mcp_fallback",
-              "selected": false,
-              "source": "internal/cli/schema_mcp_metadata.json#tools.devdoc.search_open_platform_docs_rag.interface_ref",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "available"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "available"
         },
         "avoid_when": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "搜索用户业务文档用 drive/wiki/doc，不要用 devdoc",
                 "要执行开放平台应用配置变更时用 dev"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "搜索用户业务文档用 drive/wiki/doc，不要用 devdoc",
             "要执行开放平台应用配置变更时用 dev"
@@ -110,100 +97,94 @@
         "canonical_path": {
           "candidates": [
             {
-              "precedence": "command_registry",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "reviewed_command_registry",
-              "source_ref": "devdoc article search",
-              "value": "devdoc.search_open_platform_docs_rag"
-            },
-            {
-              "precedence": "reviewed_manual",
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
-              "selected": false,
-              "source": "reviewed_manual_hint",
-              "source_ref": "devdoc article search",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "devdoc.search_open_platform_docs_rag"
             }
           ],
-          "precedence": "command_registry",
-          "resolution": "registry_identity",
-          "source": "reviewed_command_registry",
-          "source_ref": "devdoc article search",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "devdoc.search_open_platform_docs_rag"
         },
         "confirmation": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "value": "not_required"
-            },
-            {
-              "precedence": "inference_or_default",
-              "selected": false,
-              "source": "risk-default",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "not_required"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "not_required"
         },
         "description": {
           "candidates": [
             {
-              "precedence": "cobra_help",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "cobra_help",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "按关键词搜索 open.dingtalk.com 文档，支持分页。默认表格输出，可用 -f json 获取完整响应。"
-            },
-            {
-              "precedence": "mcp_metadata",
-              "selected": false,
-              "source": "mcp_metadata",
-              "value": "根据关键词搜索钉钉开放平台的开发文档，返回匹配的文档条目列表，包含标题、摘要、文档链接和相关标签。搜索结果按相关性排序。适用于开发者在集成或调试过程中快速查找 API 说明、接入指南、错误码解释等技术资料。"
             }
           ],
-          "precedence": "cobra_help",
-          "resolution": "highest_precedence",
-          "source": "cobra_help",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "按关键词搜索 open.dingtalk.com 文档，支持分页。默认表格输出，可用 -f json 获取完整响应。"
         },
         "effect": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "command-verb",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "read"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "command-verb",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "read"
         },
         "examples": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "dws devdoc article search --query \"OAuth2 接入\" --format json",
                 "dws devdoc article search --query \"errcode 40078\" --format json"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "dws devdoc article search --query \"OAuth2 接入\" --format json",
             "dws devdoc article search --query \"errcode 40078\" --format json"
@@ -212,60 +193,58 @@
         "idempotency": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "effect-default",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "idempotent"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "effect-default",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "idempotent"
         },
         "interface_mode": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "value": "mcp"
-            },
-            {
-              "precedence": "mcp_fallback",
-              "selected": false,
-              "source": "internal/cli/schema_mcp_metadata.json#tools.devdoc.search_open_platform_docs_rag.interface_ref",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "mcp"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "mcp"
         },
         "interface_ref": {
           "candidates": [
             {
-              "precedence": "imported",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/imported/wukong.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": {
                 "product_id": "devdoc",
                 "rpc_name": "search_open_platform_docs"
               }
-            },
-            {
-              "precedence": "mcp_fallback",
-              "selected": false,
-              "source": "internal/cli/schema_mcp_metadata.json#tools.devdoc.search_open_platform_docs_rag.interface_ref",
-              "value": "devdoc.search_open_platform_docs"
             }
           ],
-          "precedence": "imported",
-          "resolution": "highest_precedence",
-          "source": "internal/cli/schema_hints/imported/wukong.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": {
             "product_id": "devdoc",
             "rpc_name": "search_open_platform_docs"
@@ -274,90 +253,93 @@
         "metadata_source": {
           "candidates": [
             {
-              "precedence": "derived_resolution",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "metadata_source_resolution",
-              "value": "embedded-mcp-metadata"
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
+              "value": "corecmd.contract"
             }
           ],
-          "precedence": "derived_resolution",
-          "resolution": "highest_precedence",
-          "source": "metadata_source_resolution",
-          "value": "embedded-mcp-metadata"
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
+          "value": "corecmd.contract"
         },
         "reviewed": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/devdoc.json",
-              "value": true
-            },
-            {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-              "selected": false,
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": true
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Search text may be supplied as positional keyword or public --query; hidden --keyword remains a runtime compatibility alias and is intentionally not published as a parameter. The versioned binding owns query -\u003e keyword.",
-          "source": "internal/cli/schema_hints/metadata/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": true
         },
         "risk": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "effect-default",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "low"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "effect-default",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "low"
         },
         "title": {
           "candidates": [
             {
-              "precedence": "cobra_help",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "cobra_help",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "搜索开放平台文档"
-            },
-            {
-              "precedence": "mcp_metadata",
-              "selected": false,
-              "source": "mcp_metadata",
-              "value": "search_open_platform_docs"
             }
           ],
-          "precedence": "cobra_help",
-          "resolution": "highest_precedence",
-          "source": "cobra_help",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "搜索开放平台文档"
         },
         "use_when": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/devdoc.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "查 OpenAPI、字段、错误码、OAuth2、接入指南等开放平台开发问题"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/devdoc.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "查 OpenAPI、字段、错误码、OAuth2、接入指南等开放平台开发问题"
           ]
@@ -372,7 +354,7 @@
         "rpc_name": "search_open_platform_docs"
       },
       "is_alias": false,
-      "metadata_source": "embedded-mcp-metadata",
+      "metadata_source": "corecmd.contract",
       "name": "search_open_platform_docs_rag",
       "parameter_count": 3,
       "parameters": {

internal/cli/schema_catalog/tools/live.json

@@ -2,24 +2,12 @@
   "product": "live",
   "tools": {
     "live.get_my_lives": {
-      "agent_metadata_source": "embedded-skill-metadata",
+      "agent_metadata_source": "corecmd.contract",
       "agent_source_refs": [
-        "CommandRegistry:canonical_path=live.get_my_lives",
-        "Skill:skills/multi/dingtalk-live/SKILL.md",
-        "cobra-help:dws live stream list",
-        "dws-wukong-envelope@4574f7022c32:dws-wukong-discovery.live.prod.json#live.get_my_lives",
-        "internal/cli/schema_command_registry.json#live.get_my_lives",
-        "internal/cli/schema_hints/imported/wukong.json",
-        "internal/cli/schema_hints/metadata/live.json",
-        "internal/cli/schema_hints/selection/live.json",
-        "internal/cli/schema_mcp_metadata.json#tools.live.get_my_lives",
-        "live-dws-schema:live.get_my_lives",
-        "skills/mono/references/products/live.md",
-        "structured-hint:internal/cli/schema_hints/imported/wukong.json#live.get_my_lives",
-        "structured-hint:internal/cli/schema_hints/selection-review.json#live.get_my_lives"
+        "corecmd.SchemaDecl"
       ],
       "agent_summary": "查看当前用户发起的直播列表与基础统计",
-      "agent_summary_source": "dws-agent-selection/live",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "需要创建/开播/结束直播时不要使用；当前公开面仅列表查询"
@@ -28,10 +16,10 @@
       "cli_name": "list",
       "cli_path": "live stream list",
       "confirmation": "not_required",
-      "description": "查看我的直播列表",
+      "description": "查看当前用户发起的直播列表与基础统计",
       "display": "直播列表 / 信息",
       "effect": "read",
-      "effect_source": "command-verb",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws live stream list"
       ],
@@ -39,57 +27,57 @@
         "agent_summary": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/live.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "查看当前用户发起的直播列表与基础统计"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "查看当前用户发起的直播列表与基础统计"
         },
         "availability": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/live.json",
-              "value": "available"
-            },
-            {
-              "precedence": "mcp_fallback",
-              "selected": false,
-              "source": "internal/cli/schema_mcp_metadata.json#tools.live.get_my_lives.interface_ref",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "available"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
-          "source": "internal/cli/schema_hints/metadata/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "available"
         },
         "avoid_when": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/live.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "需要创建/开播/结束直播时不要使用；当前公开面仅列表查询"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "需要创建/开播/结束直播时不要使用；当前公开面仅列表查询"
           ]
@@ -97,83 +85,93 @@
         "canonical_path": {
           "candidates": [
             {
-              "precedence": "command_registry",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "reviewed_command_registry",
-              "source_ref": "live stream list",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "live.get_my_lives"
             }
           ],
-          "precedence": "command_registry",
-          "resolution": "registry_identity",
-          "source": "reviewed_command_registry",
-          "source_ref": "live stream list",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "live.get_my_lives"
         },
         "confirmation": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "risk-default",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "not_required"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "risk-default",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "not_required"
         },
         "description": {
           "candidates": [
             {
-              "precedence": "cobra_help",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "cobra_help",
-              "value": "查看我的直播列表"
-            },
-            {
-              "precedence": "mcp_metadata",
-              "selected": false,
-              "source": "mcp_metadata",
-              "value": "获取当前用户发起的直播列表，包含每场直播的基础信息与统计数据。返回字段包括：直播标题、封面图 URL、直播 ID、主播昵称、开始/结束时间戳、播放时长（毫秒）、观看量（UV）及直播状态（如已结束）。数据按分页返回，支持判断是否还有更多内容。适用于个人直播管理、历史记录查看等场景，仅展示当前用户有权限访问的直播内容。"
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
+              "value": "查看当前用户发起的直播列表与基础统计"
             }
           ],
-          "precedence": "cobra_help",
-          "resolution": "highest_precedence",
-          "source": "cobra_help",
-          "value": "查看我的直播列表"
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
+          "value": "查看当前用户发起的直播列表与基础统计"
         },
         "effect": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "command-verb",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "read"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "command-verb",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "read"
         },
         "examples": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/live.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "dws live stream list"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "dws live stream list"
           ]
@@ -181,60 +179,58 @@
         "idempotency": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "effect-default",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "idempotent"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "effect-default",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "idempotent"
         },
         "interface_mode": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/live.json",
-              "value": "mcp"
-            },
-            {
-              "precedence": "mcp_fallback",
-              "selected": false,
-              "source": "internal/cli/schema_mcp_metadata.json#tools.live.get_my_lives.interface_ref",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "mcp"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
-          "source": "internal/cli/schema_hints/metadata/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "mcp"
         },
         "interface_ref": {
           "candidates": [
             {
-              "precedence": "imported",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/imported/wukong.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": {
                 "product_id": "live",
                 "rpc_name": "get_my_lives"
               }
-            },
-            {
-              "precedence": "mcp_fallback",
-              "selected": false,
-              "source": "internal/cli/schema_mcp_metadata.json#tools.live.get_my_lives.interface_ref",
-              "value": "live.get_my_lives"
             }
           ],
-          "precedence": "imported",
-          "resolution": "highest_precedence",
-          "source": "internal/cli/schema_hints/imported/wukong.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": {
             "product_id": "live",
             "rpc_name": "get_my_lives"
@@ -243,90 +239,93 @@
         "metadata_source": {
           "candidates": [
             {
-              "precedence": "derived_resolution",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "metadata_source_resolution",
-              "value": "embedded-mcp-metadata"
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
+              "value": "corecmd.contract"
             }
           ],
-          "precedence": "derived_resolution",
-          "resolution": "highest_precedence",
-          "source": "metadata_source_resolution",
-          "value": "embedded-mcp-metadata"
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
+          "value": "corecmd.contract"
         },
         "reviewed": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/live.json",
-              "value": true
-            },
-            {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-              "selected": false,
-              "source": "internal/cli/schema_hints/selection/live.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": true
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "dws-tool-metadata/live marks this tool as reviewed",
-          "source": "internal/cli/schema_hints/metadata/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": true
         },
         "risk": {
           "candidates": [
             {
-              "precedence": "inference_or_default",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "effect-default",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "low"
             }
           ],
-          "precedence": "inference_or_default",
-          "resolution": "highest_precedence",
-          "source": "effect-default",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "low"
         },
         "title": {
           "candidates": [
             {
-              "precedence": "cobra_help",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "cobra_help",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "查看我的直播列表"
-            },
-            {
-              "precedence": "mcp_metadata",
-              "selected": false,
-              "source": "mcp_metadata",
-              "value": "获取当前用户发起的直播列表"
             }
           ],
-          "precedence": "cobra_help",
-          "resolution": "highest_precedence",
-          "source": "cobra_help",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "查看我的直播列表"
         },
         "use_when": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/live.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "用户要看自己发起过的直播、状态或观看量等列表信息"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "人工依据实时 dws schema（或 Skill/Cobra/pinned MCP 对照）决策化选型文案与门禁；不改写命令身份与参数契约；示例不含 --yes。",
-          "source": "internal/cli/schema_hints/selection/live.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "用户要看自己发起过的直播、状态或观看量等列表信息"
           ]
@@ -341,7 +340,7 @@
         "rpc_name": "get_my_lives"
       },
       "is_alias": false,
-      "metadata_source": "embedded-mcp-metadata",
+      "metadata_source": "corecmd.contract",
       "name": "get_my_lives",
       "parameter_count": 0,
       "parameters": {},

internal/cli/schema_catalog/tools/mcp.json

@@ -2,17 +2,12 @@
   "product": "mcp",
   "tools": {
     "mcp.url_get": {
-      "agent_metadata_source": "embedded-skill-metadata",
+      "agent_metadata_source": "corecmd.contract",
       "agent_source_refs": [
-        "cobra-help:dws mcp url get --help",
-        "internal/app/mcp_url_command.go",
-        "internal/cli/schema_command_registry.json#mcp.url_get",
-        "internal/cli/schema_hints/metadata/mcp.json",
-        "internal/cli/schema_hints/selection/mcp.json",
-        "pkg/edition/default.go#openSupplementServers"
+        "corecmd.SchemaDecl"
       ],
       "agent_summary": "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址",
-      "agent_summary_source": "dws-agent-selection/mcp",
+      "agent_summary_source": "corecmd.SchemaDecl",
       "availability": "available",
       "avoid_when": [
         "只是查询 DWS 已公开命令或参数时使用 dws schema",
@@ -25,7 +20,7 @@
       "description": "输入 MCP 市场 mcpId，返回以当前用户和组织身份访问该 MCP 的 Streamable HTTP 服务地址。\n\n安全提示：返回的 mcpURL 和 mcpJSON 可能包含身份凭据，仅限个人使用，请勿分享到群聊、文档、邮件、代码仓库或日志。",
       "display": "管理 MCP 服务连接信息",
       "effect": "read",
-      "effect_source": "agent-hint",
+      "effect_source": "corecmd.contract",
       "examples": [
         "dws mcp url get 10043 --format json"
       ],
@@ -33,52 +28,58 @@
         "agent_summary": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
-          "source": "internal/cli/schema_hints/selection/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "按 MCP 市场 mcpId 获取当前用户和组织可用的 Streamable HTTP 地址"
         },
         "availability": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "available"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "available"
         },
         "avoid_when": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "只是查询 DWS 已公开命令或参数时使用 dws schema",
                 "用户要求把返回的凭据 URL 发送到群聊、文档、邮件、日志或代码仓库时不要执行或传播"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
-          "source": "internal/cli/schema_hints/selection/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "只是查询 DWS 已公开命令或参数时使用 dws schema",
             "用户要求把返回的凭据 URL 发送到群聊、文档、邮件、日志或代码仓库时不要执行或传播"
@@ -87,81 +88,93 @@
         "canonical_path": {
           "candidates": [
             {
-              "precedence": "command_registry",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "reviewed_command_registry",
-              "source_ref": "mcp url get",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "mcp.url_get"
             }
           ],
-          "precedence": "command_registry",
-          "resolution": "registry_identity",
-          "source": "reviewed_command_registry",
-          "source_ref": "mcp url get",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "mcp.url_get"
         },
         "confirmation": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "not_required"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "not_required"
         },
         "description": {
           "candidates": [
             {
-              "precedence": "cobra_help",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "cobra_help",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "输入 MCP 市场 mcpId，返回以当前用户和组织身份访问该 MCP 的 Streamable HTTP 服务地址。\n\n安全提示：返回的 mcpURL 和 mcpJSON 可能包含身份凭据，仅限个人使用，请勿分享到群聊、文档、邮件、代码仓库或日志。"
             }
           ],
-          "precedence": "cobra_help",
-          "resolution": "highest_precedence",
-          "source": "cobra_help",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "输入 MCP 市场 mcpId，返回以当前用户和组织身份访问该 MCP 的 Streamable HTTP 服务地址。\n\n安全提示：返回的 mcpURL 和 mcpJSON 可能包含身份凭据，仅限个人使用，请勿分享到群聊、文档、邮件、代码仓库或日志。"
         },
         "effect": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "read"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "read"
         },
         "examples": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "dws mcp url get 10043 --format json"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
-          "source": "internal/cli/schema_hints/selection/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "dws mcp url get 10043 --format json"
           ]
@@ -169,136 +182,165 @@
         "idempotency": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "idempotent"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "idempotent"
         },
         "interface_mode": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "composite"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "composite"
         },
         "interface_reason": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata."
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata."
         },
         "interface_ref": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "final interface mode composite forbids a direct MCP interface_ref",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": null
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "interface_disposition_matrix",
-          "review_reason": "final interface mode composite forbids a direct MCP interface_ref",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": null
         },
+        "metadata_source": {
+          "candidates": [
+            {
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
+              "selected": true,
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
+              "value": "corecmd.contract"
+            }
+          ],
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
+          "value": "corecmd.contract"
+        },
         "reviewed": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
-              "value": true
-            },
-            {
-              "precedence": "reviewed_explicit",
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
-              "selected": false,
-              "source": "internal/cli/schema_hints/selection/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": true
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": true
         },
         "risk": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/metadata/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "medium"
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "Expose the reviewed MCP URL resolver through the public CLI and Agent Schema while preserving the helper endpoint as a non-product supplemental server. The returned URL contains user- and organization-scoped credentials and must be treated as sensitive output.",
-          "source": "internal/cli/schema_hints/metadata/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "medium"
         },
         "title": {
           "candidates": [
             {
-              "precedence": "cobra_help",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "cobra_help",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": "按 mcpId 获取 MCP 的 Streamable HTTP 服务地址"
             }
           ],
-          "precedence": "cobra_help",
-          "resolution": "highest_precedence",
-          "source": "cobra_help",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": "按 mcpId 获取 MCP 的 Streamable HTTP 服务地址"
         },
         "use_when": {
           "candidates": [
             {
-              "precedence": "reviewed_explicit",
-              "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
+              "precedence": "contract_final",
+              "review_reason": "Contract final Schema pass-through",
               "selected": true,
-              "source": "internal/cli/schema_hints/selection/mcp.json",
+              "source": "corecmd.contract",
+              "source_ref": "corecmd.SchemaDecl",
               "value": [
                 "已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"
               ]
             }
           ],
-          "precedence": "reviewed_explicit",
-          "resolution": "highest_precedence",
-          "review_reason": "正式公开 MCP URL 解析命令的 Agent 选型文案，并明确凭据 URL 只能返回给当前用户、不得二次传播。",
-          "source": "internal/cli/schema_hints/selection/mcp.json",
+          "precedence": "contract_final",
+          "resolution": "contract_pass_through",
+          "review_reason": "Contract final Schema pass-through",
+          "source": "corecmd.contract",
+          "source_ref": "corecmd.SchemaDecl",
           "value": [
             "已知钉钉 MCP 市场 mcpId，需要获得当前身份可用的 Streamable HTTP 连接地址"
           ]
@@ -310,6 +352,7 @@
       "interface_mode": "composite",
       "interface_reason": "Reviewed unpinned remote adapter: the public CLI wrapper calls the helper-only mcp-meta/get_mcp_server_url endpoint, which is intentionally absent from the public product catalog and pinned MCP metadata.",
       "is_alias": false,
+      "metadata_source": "corecmd.contract",
       "name": "url_get",
       "parameter_count": 0,
       "parameters": {},

internal/cli/schema_catalog_test.go

@@ -119,7 +119,14 @@ func TestEmbeddedCatalogPreservesRegistryIdentityAndManualParameterContract(t *t
 		t.Fatalf("source = %q, want reviewed_command_registry", got)
 	}
 	identity := schemaMap(leaf["field_provenance"])["canonical_path"]
-	if identity["source"] != "reviewed_command_registry" || identity["precedence"] != "command_registry" {
+	// Migrated ContractFinal tools stamp identity provenance as contract_final
+	// pass-through while the registry remains the path index; accept either.
+	switch identity["precedence"] {
+	case "command_registry", "contract_final":
+	default:
+		t.Fatalf("canonical identity provenance = %#v", identity)
+	}
+	if identity["precedence"] == "command_registry" && identity["source"] != "reviewed_command_registry" {
 		t.Fatalf("canonical identity provenance = %#v", identity)
 	}
 	parameters := schemaMap(leaf["parameters"])

internal/cli/schema_cobra_binding.go

@@ -159,6 +159,20 @@ func BindEffectiveCommandRegistry(root *cobra.Command, effective EffectiveComman
 		for _, alias := range item.Aliases {
 			bound.ByCLIPath[alias] = item
 		}
+		// Migrate reviewed hint facts onto undeclared leaves without replacing
+		// their Execute/RunE bodies. Already-declared ContractFinal (e.g. LeafSpec
+		// Schema) wins and is left untouched — execution stays the control variable.
+		if !HasRuntimeContractFinal(item.PrimaryCommand) {
+			if decl, ok := lookupSchemaHintDecl(item.CanonicalPath); ok {
+				attachSchemaHintDecl(item.PrimaryCommand, decl)
+			}
+		}
+		// Index Contract-declared dry_run capabilities at bind time: every
+		// process that resolves the command tree gets the reviewed set, not
+		// only processes that also run Schema assembly.
+		if payload, ok := RuntimeContractFinal(item.PrimaryCommand); ok && payload.DryRun != nil {
+			recordDeclaredDryRunCapability(item.CanonicalPath, *payload.DryRun)
+		}
 	}
 	return bound, nil
 }

internal/cli/schema_cobra_binding_test.go

@@ -11,6 +11,50 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// TestBindEffectiveCommandRegistryIndexesDeclaredDryRun pins bind-time
+// capability indexing: any process resolving the command tree gets the
+// Contract-declared dry_run in the reviewed set, without running assembly.
+func TestBindEffectiveCommandRegistryIndexesDeclaredDryRun(t *testing.T) {
+	clearDeclaredDryRunCapabilitiesForTest()
+	t.Cleanup(clearDeclaredDryRunCapabilitiesForTest)
+
+	root := commandRegistryTestRoot("item get")
+	leaf := exactSchemaCommand(root, "item get")
+	RegisterRuntimeContractFinal(leaf, ContractFinalPayload{
+		DryRun: &DryRunSpec{PreviewKind: DryRunPreviewInvocation},
+	})
+	t.Cleanup(func() { ClearRuntimeContractFinalForTest(leaf) })
+
+	reviewed := mustCommandRegistry(t, []CommandSpec{{
+		CanonicalPath:  "item.get_item",
+		PrimaryCLIPath: "item get",
+	}})
+	manual := ManualSchemaHintSnapshot{
+		Version: manualSchemaHintVersion,
+		Commands: []ManualSchemaCommandHint{{
+			CLIPath:       "item get",
+			CanonicalPath: "item.get_item",
+			Reason:        "Confirms the reviewed primary identity",
+			Reviewed:      true,
+		}},
+	}
+	effective, err := buildEffectiveCommandRegistry(root, reviewed, manual)
+	if err != nil {
+		t.Fatalf("buildEffectiveCommandRegistry() error = %v", err)
+	}
+	if _, err := BindEffectiveCommandRegistry(root, effective); err != nil {
+		t.Fatalf("BindEffectiveCommandRegistry() error = %v", err)
+	}
+	capabilities, err := loadReviewedDryRunCapabilities()
+	if err != nil {
+		t.Fatal(err)
+	}
+	spec, ok := capabilities["item.get_item"]
+	if !ok || spec.PreviewKind != DryRunPreviewInvocation {
+		t.Fatalf("declared dry-run capability after bind = %#v, ok=%v", spec, ok)
+	}
+}
+
 func TestBuildEffectiveCommandRegistryMergesReviewedManualCommands(t *testing.T) {
 	root := commandRegistryTestRoot("item get", "item legacy", "helper add")
 	annotateTestCompatibilityPair(exactSchemaCommand(root, "item get"), exactSchemaCommand(root, "item legacy"))

internal/cli/schema_contract_model.go

@@ -260,9 +260,12 @@ type SelectionSpec struct {
 	Tips               []string
 	WorkflowRefs       []string
 	Examples           []string
-	Reviewed           *bool
-	SourceRefs         []string
-	MetadataSource     string
+	// Reviewed is a legacy-path (hints/registry) marker only. The Contract
+	// declaration path must not set it: declared selection is final by
+	// construction, and assembly rejects a declared payload carrying it.
+	Reviewed       *bool
+	SourceRefs     []string
+	MetadataSource string
 }
 
 // FieldProvenance records how one final field was selected. Value is raw JSON

internal/cli/schema_dry_run_capabilities.go

@@ -17,36 +17,17 @@ type dryRunCapabilityGroup struct {
 	CanonicalPaths []string
 }
 
-// reviewedDryRunCapabilityGroups contains only command-owned preview paths.
+// reviewedDryRunCapabilityGroups contains only command-owned preview paths
+// for tools WITHOUT a Contract final declaration. Declared tools publish
+// their dry_run capability from corecmd.SchemaDecl (reviewed code) and are
+// merged into the reviewed set at assembly time — no manual list entry.
 // Inheriting the root --dry-run flag or reaching the generic EchoRunner is not
 // evidence of a stable capability and must never add a command to this list.
 // CI executes each selected example and compares the observed preview kind to
 // this reviewed declaration.
 var reviewedDryRunCapabilityGroups = []dryRunCapabilityGroup{
-	{PreviewKind: DryRunPreviewRequest, CanonicalPaths: []string{
-		"event.stop",
-	}},
-	{PreviewKind: DryRunPreviewPlan, CanonicalPaths: []string{
-		"chat.download_media",
-		"doc.download_file",
-		"doc.import_get",
-		"doc.media_insert",
-		"doc.query_export_job",
-		"doc.upload",
-		"drive.download_file",
-		"drive.upload",
-		"markdown.create",
-		"markdown.fetch",
-		"markdown.overwrite",
-		"markdown.patch",
-		"sheet.filter_view_get_criteria",
-		"sheet.filter_view_info",
-		"sheet.filter_view_list_criteria",
-		"sheet.media_upload",
-		"sheet.submit_export_job",
-		"sheet.write_image",
-		"todo.add_todo_attachment",
-	}},
+	// Declared tools publish dry_run from schemaHintDecls / LeafSpec Schema.
+	// Manual entries remain only for tools that cannot yet declare ContractFinal.
 }
 
 var reviewedDryRunCapabilitiesLazy struct {
@@ -55,7 +36,34 @@ var reviewedDryRunCapabilitiesLazy struct {
 	err         error
 }
 
-func loadReviewedDryRunCapabilities() (map[string]DryRunSpec, error) {
+// declaredDryRunCapabilities indexes dry_run capabilities sourced from
+// Contract final declarations (canonical → spec). Populated by
+// BindEffectiveCommandRegistry at command-tree bind time — every process
+// that resolves the tree gets the reviewed set, not only processes that run
+// Schema assembly. A declaration in reviewed code is itself the reviewed
+// capability, so no manual allowlist entry is required.
+var declaredDryRunCapabilities sync.Map // string → DryRunSpec
+
+// recordDeclaredDryRunCapability registers one Contract-declared dry_run
+// capability. Conflicting re-declaration of the same canonical is a
+// programming error surfaced at the next delivery gate read.
+func recordDeclaredDryRunCapability(canonical string, spec DryRunSpec) {
+	canonical = strings.TrimSpace(canonical)
+	if canonical == "" {
+		return
+	}
+	declaredDryRunCapabilities.Store(canonical, spec)
+}
+
+// clearDeclaredDryRunCapabilitiesForTest resets the declared index (tests only).
+func clearDeclaredDryRunCapabilitiesForTest() {
+	declaredDryRunCapabilities.Range(func(key, _ any) bool {
+		declaredDryRunCapabilities.Delete(key)
+		return true
+	})
+}
+
+func loadManualDryRunCapabilities() (map[string]DryRunSpec, error) {
 	reviewedDryRunCapabilitiesLazy.once.Do(func() {
 		byCanonical := make(map[string]DryRunSpec)
 		for _, group := range reviewedDryRunCapabilityGroups {
@@ -95,6 +103,36 @@ func loadReviewedDryRunCapabilities() (map[string]DryRunSpec, error) {
 	return out, nil
 }
 
+func loadReviewedDryRunCapabilities() (map[string]DryRunSpec, error) {
+	out, err := loadManualDryRunCapabilities()
+	if err != nil {
+		return nil, err
+	}
+	var mergeErr error
+	declaredDryRunCapabilities.Range(func(key, value any) bool {
+		canonical, ok := key.(string)
+		if !ok {
+			mergeErr = fmt.Errorf("declared dry-run capability has non-string key %v", key)
+			return false
+		}
+		spec, ok := value.(DryRunSpec)
+		if !ok {
+			mergeErr = fmt.Errorf("declared dry-run capability %s has non-DryRunSpec value", canonical)
+			return false
+		}
+		if manual, exists := out[canonical]; exists && manual != spec {
+			mergeErr = fmt.Errorf("dry-run capability %s declared as %#v conflicts with manual reviewed entry %#v", canonical, spec, manual)
+			return false
+		}
+		out[canonical] = spec
+		return true
+	})
+	if mergeErr != nil {
+		return nil, mergeErr
+	}
+	return out, nil
+}
+
 // ReviewedDryRunCapabilities returns a defensive copy of the positive,
 // reviewed capability registry for delivery gates.
 func ReviewedDryRunCapabilities() (map[string]DryRunSpec, error) {

internal/cli/schema_hint_decls.go

@@ -0,0 +1,95 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package cli
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// schemaHintDecl is one command's Safety + Schema migrated from reviewed
+// schema_hints selection/metadata into compiled Go.
+type schemaHintDecl struct {
+	Safety      SafetySpec
+	Description string
+	DryRun      *DryRunSpec
+	Interface   *InterfaceSpec
+	Selection   SelectionSpec
+}
+
+// lookupSchemaHintDecl returns the migrated declaration for a canonical path.
+func lookupSchemaHintDecl(canonical string) (schemaHintDecl, bool) {
+	canonical = strings.TrimSpace(canonical)
+	if canonical == "" {
+		return schemaHintDecl{}, false
+	}
+	d, ok := schemaHintDeclsByCanonical[canonical]
+	return d, ok
+}
+
+// attachSchemaHintDecl registers ContractFinal from a migrated hint declaration
+// without replacing RunE/Execute. Completeness is enforced here so bind-time
+// attaches cannot ship a partial overlay.
+func attachSchemaHintDecl(cmd *cobra.Command, decl schemaHintDecl) {
+	if cmd == nil {
+		return
+	}
+	if strings.TrimSpace(decl.Description) == "" {
+		panic(fmt.Sprintf("schema hint decl for %s missing Description", cmd.CommandPath()))
+	}
+	if strings.TrimSpace(decl.Selection.AgentSummary) == "" ||
+		len(decl.Selection.UseWhen) == 0 || len(decl.Selection.AvoidWhen) == 0 ||
+		len(decl.Selection.Examples) == 0 {
+		panic(fmt.Sprintf("schema hint decl for %s missing Selection prose", cmd.CommandPath()))
+	}
+	if decl.Interface == nil || strings.TrimSpace(decl.Interface.Mode) == "" ||
+		strings.TrimSpace(decl.Interface.Availability) == "" {
+		panic(fmt.Sprintf("schema hint decl for %s missing Interface", cmd.CommandPath()))
+	}
+	if (decl.Interface.Mode == InterfaceModeComposite ||
+		decl.Interface.Availability == InterfaceUnavailable) &&
+		strings.TrimSpace(decl.Interface.Reason) == "" {
+		panic(fmt.Sprintf("schema hint decl for %s missing Interface.Reason", cmd.CommandPath()))
+	}
+
+	safety := decl.Safety
+	if strings.TrimSpace(safety.Effect) == "" && strings.TrimSpace(safety.Risk) == "" &&
+		strings.TrimSpace(safety.Confirmation) == "" && strings.TrimSpace(safety.Idempotency) == "" {
+		safety = SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		}
+	}
+	safety.EffectSource = "corecmd.contract"
+
+	payload := ContractFinalPayload{
+		Title:       firstNonEmptyTrim(cmd.Short),
+		Description: firstNonEmptyTrim(decl.Description, cmd.Long),
+		Safety:      &safety,
+		DryRun:      decl.DryRun,
+		Interface:   decl.Interface,
+		Selection: &SelectionSpec{
+			AgentSummary:  strings.TrimSpace(decl.Selection.AgentSummary),
+			UseWhen:       decl.Selection.UseWhen,
+			AvoidWhen:     decl.Selection.AvoidWhen,
+			Prerequisites: decl.Selection.Prerequisites,
+			Tips:          decl.Selection.Tips,
+			WorkflowRefs:  decl.Selection.WorkflowRefs,
+			Examples:      decl.Selection.Examples,
+		},
+	}
+	RegisterRuntimeContractFinal(cmd, payload)
+}
+
+func firstNonEmptyTrim(values ...string) string {
+	for _, v := range values {
+		if s := strings.TrimSpace(v); s != "" {
+			return s
+		}
+	}
+	return ""
+}

internal/cli/schema_hint_decls_generated.go

@@ -0,0 +1,10 @@
+// Copyright 2026 Alibaba Group
+//
+// Intentionally empty after the ContractFinal migration: leaf and shortcut
+// declarations now live in helpers.DeclareLeafMetadata / Shortcut.Schema, so the
+// lookup in schema_hint_decls.go always misses and callers fall through to the
+// declaration path. No generator maintains this table.
+
+package cli
+
+var schemaHintDeclsByCanonical = map[string]schemaHintDecl{}

internal/cli/schema_hint_decls_test.go

@@ -0,0 +1,71 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func testSchemaHintDeclFixture() schemaHintDecl {
+	return schemaHintDecl{
+		Safety: SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Description: "fixture command for attachSchemaHintDecl freeze test",
+		Interface: &InterfaceSpec{
+			Mode: InterfaceModeMCP, Availability: InterfaceAvailable,
+			Ref: &InterfaceRefSpec{ProductID: "fixture", RPCName: "fixture_probe"},
+		},
+		Selection: SelectionSpec{
+			AgentSummary: "fixture probe",
+			UseWhen:      []string{"unit testing attachSchemaHintDecl"},
+			AvoidWhen:    []string{"production use"},
+			Examples:     []string{"dws fixture probe"},
+		},
+	}
+}
+
+func TestSchemaHintDeclAttachDoesNotReplaceRunE(t *testing.T) {
+	ran := false
+	cmd := &cobra.Command{
+		Use:   "probe",
+		Short: "probe",
+		RunE: func(*cobra.Command, []string) error {
+			ran = true
+			return nil
+		},
+	}
+	attachSchemaHintDecl(cmd, testSchemaHintDeclFixture())
+	if !HasRuntimeContractFinal(cmd) {
+		t.Fatal("expected ContractFinal after attach")
+	}
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if !ran {
+		t.Fatal("RunE body was not invoked — execution must stay frozen")
+	}
+	ClearRuntimeContractFinalForTest(cmd)
+}
+
+func TestSchemaHintDeclLookupCoverage(t *testing.T) {
+	// All reviewed tools now author ContractFinal beside the command
+	// (DeclareLeafMetadata / Shortcut.Schema). The compiled residual map is empty.
+	if got := len(schemaHintDeclsByCanonical); got != 0 {
+		t.Fatalf("compiled residual decls = %d, want 0 after full colocation", got)
+	}
+	if _, ok := lookupSchemaHintDecl("aitable.view_update_aggregate"); ok {
+		t.Fatal("aitable.view_update_aggregate must not remain in compiled hint decls")
+	}
+	if _, ok := lookupSchemaHintDecl("aitable.shortcut_base_list"); ok {
+		t.Fatal("aitable.shortcut_base_list must not remain in compiled hint decls")
+	}
+	if _, ok := lookupSchemaHintDecl("doc.create_document"); ok {
+		t.Fatal("doc.create_document must not remain in compiled hint decls")
+	}
+}

internal/cli/schema_hints/metadata/aisearch.json

@@ -8,15 +8,7 @@
     "reviewed": true
   },
   "tools": {
-    "aisearch.enterprise_person_search": {
-      "interface_mode": "mcp",
-      "availability": "available",
-      "reviewed": true
-    },
     "aisearch.search_enterprise": {
-      "interface_mode": "mcp",
-      "availability": "available",
-      "reviewed": true,
       "parameters": {
         "queries": {
           "required": false
@@ -25,15 +17,9 @@
           "required": false
         }
       },
-      "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input.",
+      "reviewed": true,
       "cli_path": "aisearch enterprise",
-      "runtime_gate": "none",
-      "confirmation": "not_required"
-    },
-    "aisearch.search_enterprise_behavior": {
-      "interface_mode": "mcp",
-      "availability": "available",
-      "reviewed": true
+      "review_reason": "The reviewed CLI supports an all-content search with default --types all, while --queries and --time-range are optional filters; imported MCP required markers must not turn them into mandatory CLI input."
     }
   }
 }