draftgo-cli 3.0.55 → 4.0.1

package/resources/skill/references/mcp.md

@@ -4,62 +4,44 @@ read_when: 配置或诊断 DraftGo MCP 时 · 查询实时资源或 API 契约
 
 # DraftGo MCP
 
-> 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明实时 MCP 的边界和调用顺序，不能替代页面、前端、运行时、安全或模块资料。
+根 `SKILL.md` 已负责任务路由。本文件只保留 MCP 的实时契约、调用优化和安全边界，不重复页面、前端或交付规则。
 
 ## 边界
 
-DraftGo MCP 用于实时发现、结构化查询和普通 API 操作。完整 pages、navigations、docs/articles 正文不通过
-MCP tool result 或参数传输；需要全文时使用 `draftgo checkout`，提交时使用 `draftgo commit`。MCP 返回
-`artifact` / `omitted` 时保留该语义，不要尝试重新展开长内容。
+MCP 用于实时发现、结构化查询和普通 API 操作。pages、navigations、docs/articles、custom_services 的完整正文走 `draftgo checkout` / `draftgo commit`；工具返回 `artifact` 或 `omitted` 时保留该语义，不要求模型展开长内容。
 
-不要在 CLI 或 MCP 服务端增加聚合上下文工具。自然语言任务的语义筛选由已加载根 Skill 的 Agent 完成：先读取任务路由指定的最少必要 Reference，再调用下面的精确 MCP 工具，并根据结果逐步缩小范围。
+不要增加聚合上下文工具或静态 API 路径表。按任务读取最少必要的 Reference，再调用精确工具：
 
-标准发现顺序：
+| 需要 | 工具 |
+|---|---|
+| 项目能力、registry 覆盖和 checkout 类型 | `draftgo_project_overview` |
+| 定位资源 | `draftgo_resource_search` / `draftgo_resource_list` |
+| 元数据或短片段 | `draftgo_resource_get_metadata` / `draftgo_resource_read_fragment` |
+| 定位 API operation | `draftgo_api_search` |
+| 读取 operation schema | `draftgo_api_describe` |
+| 结构化读写 | `draftgo_api_call` |
 
-1. `draftgo_project_overview`
-2. `draftgo_resource_search` 或 `draftgo_resource_list`
-3. 按需调用 `draftgo_resource_get_metadata` 或 `draftgo_resource_read_fragment`
-4. 需要实时 API 契约时调用 `draftgo_api_search`、`draftgo_api_describe`
-5. 结构化资源读写使用 `draftgo_api_call`
+只在需要对应信息时调用工具，不把 `project_overview` 作为每个任务的固定前置步骤。独立资源或 operation 可并发调用；同一资源的依赖步骤保持顺序。非幂等写入失败后先读状态，不自动重试。
 
-结构化资源包括 db_meta、AIHub、system_config、roles、users、doc_categories 和自定义服务元数据。
-这些资源不 checkout，也不生成 `.draftgo/*/index.json` 镜像。
+## API 契约缓存
 
-## API 发现与调用
+动态 schema 不写入 Skill。Skill 只保存下面的缓存规则：
 
-静态 API 路径表不是事实来源。每次调用都按 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 执行，不能从旧文档、经验或相似 operation 猜参数。
+1. operation 未知时才 search；已有精确 `operation_id` 时跳过 search。
+2. 第一次使用 operation 时 describe，检查 method、path、parameters、request body、responses、permission、risk、`destructive`、`idempotent`、`input_schema` 和 `response_policy`。
+3. 同一 server 的 operation 描述按 `registry_revision` 复用。CLI 将缓存写在私有 `.draftgo/api-contract-cache.json`，不把 schema 注入 Skill 或对话上下文。
+4. call 携带缓存的 `registry_revision`。服务返回 `CONTRACT_CHANGED` 时重新 describe 并重试一次；其他工具错误不触发自动重试。
 
-### 1. 搜索 operation
+describe 缺少本次调用需要的 schema、权限、风险或响应契约时停止并报告，不猜字段、不拼路径、不绕过 MCP。多个 operation 仍可能匹配时继续缩小 search，而不是任选一个。
 
-```json
-{
-  "query": "需要查找的能力或路径片段",
-  "module": "可选模块",
-  "resource_type": "可选资源类型",
-  "limit": 100,
-  "cursor": "下一页游标"
-}
-```
+动态 Go 自定义服务 Route 也在 registry 中：module 为 `scripts_dynamic`，resource type 为 `custom_scripts`。Route 的 SDK、身份和运行限制见 `custom-services.md`。
 
-`query`、`module`、`resource_type` 可组合筛选。结果提供 `operation_id`、method、path、module、resource type、permission、risk、`destructive` 和 `idempotent`。需要完整候选集时持续读取 `next_cursor`，直到没有下一页；不要因首批搜索结果为空或同名 operation 较多就猜测端点。
-
-动态 Go 自定义服务也在同一 registry：有效的 `app.Route` 会实时物化为实际 method 与 `/api/x/{slug}/{path}` operation，module 为 `scripts_dynamic`、resource type 为 `custom_scripts`。SDK、身份继承、精确匹配和运行限制仍以 `references/custom-services.md` 为准。
-
-### 2. 描述唯一 operation
-
-```json
-{ "operation_id": "search 返回的精确 operation_id" }
-```
-
-调用前必须检查 describe 返回的 method、path、parameters、request body、responses、examples、permission、risk、`destructive`、`idempotent`、完整 `input_schema` 和 `response_policy`。路径参数放 `path`，查询参数放 `query`，JSON 请求体放 `body`，文件或表单字段放 `multipart`；只发送 schema 允许的字段。
-
-describe 缺少与本次调用有关的参数、请求体、responses、permission、risk、`input_schema` 或 `response_policy` 时停止并报告契约不完整，不得自行补字段、改走猜测路径或绕过 MCP。若多个 operation 仍可能匹配，继续缩小搜索范围，而不是任选一个。
-
-### 3. 调用
+## 调用形状
 
 ```json
 {
   "operation_id": "精确 operation_id",
+  "registry_revision": "describe 返回的 revision",
   "path": {},
   "query": {},
   "body": null,
@@ -68,11 +50,11 @@ describe 缺少与本次调用有关的参数、请求体、responses、permissi
 }
 ```
 
-仅传需要的容器。`draftgo_api_call` 会按该 operation 的 `input_schema` 拒绝未知字段，并以当前 MCP principal 执行权限检查；不要传 tenant override、SAT、Authorization 或其他凭据。高风险 operation 只有在用户意图明确、影响范围已核对时才把 `confirm` 设为 `true`；`confirm` 是 MCP 的风险确认字段，不要自行拼接 `X-Confirm-Token` 或调用旧式 reauth 流程。
+只传 operation schema 需要的容器。路径参数放 `path`，查询参数放 `query`，JSON 放 `body`，文件或表单字段放 `multipart`。不得传 tenant override、SAT、Authorization 或其他凭据。
 
-按 describe 的 responses 与实际 `status_code` 解析结果。标准管理 API 通常使用 `{code, data, message}`，但 OpenAI 兼容流、模型列表和自定义 Route 等响应可不同；不得对所有 operation 强套统一信封。`response_policy.checkout_required=true` 或长正文资源的完整内容必须转用 `draftgo checkout` / `draftgo commit`，不能塞进 `body`、`multipart` 或工具结果。
+高风险 operation 仅在用户意图和影响范围明确时设置 `confirm=true`；不要拼 `X-Confirm-Token` 或调用旧 reauth 流程。按 describe 的 responses 与实际 `status_code` 解释结果，不对自定义 Route、OpenAI 兼容流等强套 `{code,data,message}`。`response_policy.checkout_required=true` 时改走 checkout/commit。
 
-## CLI
+## CLI 与宿主
 
 ```bash
 draftgo mcp setup [target...]
@@ -81,72 +63,26 @@ draftgo mcp test
 draftgo mcp serve
 ```
 
-- `setup` 写入项目级宿主配置，只替换 `draftgo` MCP 条目并保留其他配置。
-- `status` 检查配置是否存在、格式是否有效，以及是否误写了凭据或远端 URL。
-- `test` 从 `.draftgo/config.json` 读取连接，验证 initialize、tools/list、三类正文 resource_list，以及 db_meta 的 api_search、api_describe 和只读 api_call。
-- `serve` 启动 stdio bridge，把宿主请求代理到当前项目配置的远端 Streamable HTTP `/mcp`。远端重启或 session 过期后，bridge 会清除旧 `Mcp-Session-Id`、重新 initialize，并对被明确拒绝为 session 无效的当前请求重试一次；普通超时、服务端错误和工具错误不会自动重试。
-
-`draftgo mcp test` 每次使用独立的新连接，因此它证明当前 server、SAT 和协议可以建立新 session，不代表宿主已持有的旧 session 仍然有效。宿主工具报告 session 失效但 `mcp test` 成功时，bridge 应自动恢复；若恢复仍失败，再检查远端日志、代理头传递和服务可用性。
+- `setup` 写项目级宿主配置，只替换 `draftgo` 条目。
+- `status` 检查配置与凭据泄漏风险。
+- `test` 建立独立新连接并验证关键工具；它不证明宿主持有的旧 session 仍有效。
+- `serve` 是 stdio bridge。远端 session 明确失效时重新 initialize 并重放当前请求一次；普通超时、服务错误和工具错误不重试。
 
-`draftgo connect` 保存并验证 server/SAT、探测 `/mcp` 和关键工具，并可提示宿主 setup；`--server` 表示基础地址，完整 MCP endpoint 使用 `--mcp-url` 显式传入。它不下载业务资源，
-也不创建 pages、navigation、docs、db_meta 等本地镜像。底座仍在开发或暂不可达时，报告诊断结果即可，
-不得回退到 `pull --all`。
+支持项目级 setup：Codex、Claude Code、Cursor、Gemini CLI、Kiro、GitHub Copilot。Windsurf 和 Antigravity 没有可靠项目级 MCP 配置，CLI 应明确提示不支持。
 
-## 宿主配置
-
-| 宿主 | 项目配置 | MCP setup |
-|---|---|---|
-| Codex | `.codex/config.toml` | 支持 |
-| Claude Code | `.mcp.json` | 支持 |
-| Cursor | `.cursor/mcp.json` | 支持 |
-| Gemini CLI | `.gemini/settings.json` | 支持 |
-| Kiro | `.kiro/settings/mcp.json` | 支持 |
-| GitHub Copilot | `.vscode/mcp.json` | 支持 |
-| Windsurf | 无可靠的项目级适配 | 不支持，CLI 必须明确提示 |
-| Antigravity | 无可靠的项目级适配 | 不支持，CLI 必须明确提示 |
-
-Codex 配置：
-
-```toml
-[mcp_servers.draftgo]
-command = "draftgo"
-args = ["mcp", "serve"]
-```
-
-Claude Code、Cursor、Gemini CLI 和 Kiro 使用各自文件中的 `mcpServers`：
+宿主配置只运行：
 
 ```json
-{
-  "mcpServers": {
-    "draftgo": {
-      "command": "draftgo",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
+{"command":"draftgo","args":["mcp","serve"]}
 ```
 
-GitHub Copilot 使用 `servers`，并声明 stdio：
-
-```json
-{
-  "servers": {
-    "draftgo": {
-      "type": "stdio",
-      "command": "draftgo",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
-```
+Codex 使用 `[mcp_servers.draftgo]`；GitHub Copilot 使用 `servers` 且声明 `type="stdio"`；其他支持宿主使用各自 `mcpServers`。配置不得包含 SAT、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据命令。bridge 从当前项目 `.draftgo/config.json` 读取 server/SAT。
 
-配置中不得出现 SAT、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据的命令行。
-bridge 必须从当前工作目录的 `.draftgo/config.json` 读取 server/SAT。
+`draftgo connect` 只保存并验证连接，不下载业务资源或创建本地镜像。MCP 不可用时运行 `draftgo mcp test` 收集证据。
 
-## 协议与安全
+## 安全
 
-- stdio 只输出 MCP JSON-RPC 帧；普通日志写入 stderr，且不得包含 SAT。
-- 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座 schema 或结构化错误。
-- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前对 SAT 和 Authorization 值做脱敏。
-- `.draftgo/config.json`、`.draftgo/worktree/` 和 `.draftgo/conflicts/` 必须加入 `.gitignore`。
-- MCP 不可用时运行 `draftgo mcp test` 收集证据；不要读取旧索引作为替代事实来源。
+- stdio stdout 只输出 MCP JSON-RPC；日志写 stderr，且不得包含 SAT。
+- 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座结果。
+- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前脱敏 SAT 与 Authorization。
+- `.draftgo/config.json`、`.draftgo/api-contract-cache.json`、worktree 和 conflicts 都是私有运行时状态并应 gitignore。

package/resources/skill/references/runtime.md

@@ -94,8 +94,9 @@ const orderId = query.orderId;  // "42"
 
 ### 修改方法
 
-system_config 是结构化远端资源。修改前通过 MCP `draftgo_api_search` / `draftgo_api_describe` 获取实时契约，
-再用 `draftgo_api_call` 读取并更新目标键；不要 checkout、pull 或维护本地索引。
+system_config 是结构化远端资源。未知 operation 才通过 MCP `draftgo_api_search` 定位；首次使用或
+registry revision 变化时 `draftgo_api_describe`，再用 `draftgo_api_call` 读取并更新目标键；不要 checkout
+或维护本地索引。
 
 前端全局层是系统默认配置。更新现有全局配置时只发送 `config_value`；不要带 `description`、`category`、
 `value_type`、`status` 等元信息，避免触发“系统默认字段不允许修改字段描述/分类/状态”。

package/resources/skill/story/SKILL.md

@@ -110,9 +110,8 @@ now:
    - MCP resource_search/get_metadata → 页面与导航元数据（跳过 tag="系统" 的内置页）
    - MCP api_search/api_describe/api_call → db_meta 与自定义服务结构
    - 只有必须分析完整 pages/nav/docs 正文时才 checkout；不要要求 MCP 返回全文
-   - .draftgo/changelog.md → 更新日志
+   - .draftgo/worklog.md → 工作进度与完成记录
    - .draftgo/lessons/ → 开发经验记录
-   - .draftgo/Task/ → 历史任务文档
    - 用户提供的设计文档（PRD / 原型说明 / 需求文档）→ 提取产品意图
 
 2. 从已有数据推断系统画像，生成推断版 Story（含 design.overview 和 modules）

package/src/apiContractCache.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = 1;
+const WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+function cachePath(projectDir) {
+  return path.join(projectDir, '.draftgo', 'api-contract-cache.json');
+}
+
+function emptyCache(server) {
+  return { schema_version: SCHEMA_VERSION, server, operations: {} };
+}
+
+function readCache(projectDir, server) {
+  const file = cachePath(projectDir);
+  if (!fs.existsSync(file)) return emptyCache(server);
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!value || value.schema_version !== SCHEMA_VERSION || value.server !== server
+        || !value.operations || Array.isArray(value.operations)) return emptyCache(server);
+    return value;
+  } catch {
+    return emptyCache(server);
+  }
+}
+
+function normalizeDescription(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const operation = value.operation && typeof value.operation === 'object' ? value.operation : value;
+  const registryRevision = String(value.registry_revision || operation.registry_revision || '').trim();
+  const contractHash = String(value.contract_hash || operation.contract_hash || '').trim();
+  const operationId = String(operation.operation_id || '').trim();
+  if (!operationId || !registryRevision || !contractHash) return null;
+  const normalized = { ...operation };
+  delete normalized.registry_revision;
+  delete normalized.contract_hash;
+  return { operation: normalized, registry_revision: registryRevision, contract_hash: contractHash };
+}
+
+function cachedDescription(projectDir, server, operationId) {
+  const cached = readCache(projectDir, server).operations[String(operationId)];
+  return normalizeDescription(cached);
+}
+
+function acquire(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const lock = `${file}.lock`;
+  const started = Date.now();
+  while (true) {
+    try {
+      const descriptor = fs.openSync(lock, 'wx', 0o600);
+      fs.closeSync(descriptor);
+      return lock;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+    }
+    try {
+      if (Date.now() - fs.statSync(lock).mtimeMs > 30_000) {
+        fs.rmSync(lock, { force: true });
+        continue;
+      }
+    } catch (error) {
+      if (!error || error.code !== 'ENOENT') throw error;
+      continue;
+    }
+    if (Date.now() - started >= 2000) return null;
+    Atomics.wait(WAIT, 0, 0, 10);
+  }
+}
+
+function writeAtomic(file, value) {
+  const temporary = `${file}.tmp-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.rmSync(temporary, { force: true }); } catch { /* Best-effort cleanup. */ }
+  }
+}
+
+function storeDescription(projectDir, server, value) {
+  const normalized = normalizeDescription(value);
+  if (!normalized) return null;
+  const file = cachePath(projectDir);
+  const lock = acquire(file);
+  if (!lock) return normalized;
+  try {
+    const cache = readCache(projectDir, server);
+    cache.operations[normalized.operation.operation_id] = {
+      ...normalized,
+      described_at: new Date().toISOString(),
+    };
+    cache.updated_at = new Date().toISOString();
+    writeAtomic(file, cache);
+  } finally {
+    try { fs.rmSync(lock, { force: true }); } catch { /* Cache writes are best effort. */ }
+  }
+  return normalized;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  cachePath,
+  readCache,
+  normalizeDescription,
+  cachedDescription,
+  storeDescription,
+};

package/src/cli.js

@@ -13,8 +13,6 @@ const VALUE_FLAGS = new Set([
   'url',
   'browser',
   'browser-path',
-  'resource',
-  'mobile-check',
   'ui',
   'frame',
   'viewport',
@@ -31,30 +29,12 @@ const VALUE_FLAGS = new Set([
   'params',
   'input',
   'type',
-  'title',
-  'description',
-  'item-id',
-  'id',
-  'owner',
-  'original',
-  'original-requirement',
-  'clarified',
-  'clarified-requirement',
-  'expected-effect',
-  'effect',
-  'scope',
-  'out-of-scope',
-  'content',
-  'acceptance',
-  'module-logic',
-  'user-journey',
-  'item',
   'date',
   'handler',
   'headers',
   'user',
   'side-effect-policy',
-  'evidence',
+  'note',
 ]);
 
 function parse(argv) {

package/src/commandRegistry.js

@@ -5,15 +5,13 @@
 const commands = [
   { name: 'init', run: (dir, args, flags) => require('./commands/init')(dir, args, flags) },
   { name: 'update', run: (dir, args, flags) => require('./commands/update')(dir, args, flags) },
-  { name: 'uninstall', aliases: ['remove'], run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
+  { name: 'uninstall', run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
   { name: 'status', run: (dir) => require('./commands/status')(dir) },
-  { name: 'changelog', run: (dir, args, flags) => require('./commands/changelog')(dir, args, flags) },
-  { name: 'task', run: (dir, args, flags) => require('./commands/task')(dir, args, flags) },
+  { name: 'work', run: (dir, args, flags) => require('./commands/worklog')(dir, args, flags) },
   { name: 'clean', run: (dir, args, flags) => require('./commands/clean')(dir, args, flags) },
   { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
   { name: 'check', run: (dir, args, flags) => require('./commands/check')(dir, args, flags) },
   { name: 'verify', run: (dir, args, flags) => require('./commands/verify')(dir, args, flags) },
-  { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUiCompat')(dir, args, flags) },
   { name: 'mcp', run: (dir, args, flags) => require('./commands/mcp')(dir, args, flags) },
   { name: 'checkout', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
   { name: 'refresh', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
@@ -26,15 +24,12 @@ const commands = [
   { name: 'conflicts', run: (dir, args, flags) => require('./commands/conflicts')(dir, args, flags) },
   { name: 'conflict', run: (dir, args, flags) => require('./commands/conflict')(dir, args, flags) },
   { name: 'api', run: (dir, args, flags) => require('./commands/api')(dir, args, flags) },
-  { name: 'delete', aliases: ['del', 'rm'], run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
+  { name: 'delete', run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
   { name: 'deploy', run: (dir, args, flags) => require('./commands/deploy')(dir, args, flags) },
-  { name: 'auto-push', aliases: ['autopush'], run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },
-  { name: 'pull', run: (dir, args, flags) => require('./commands/sync')(dir, 'pull', args, flags) },
-  { name: 'push', run: (dir, args, flags) => require('./commands/sync')(dir, 'push', args, flags) },
+  { name: 'auto-push', run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },
   { name: 'local', run: (dir, args, flags) => require('./commands/local')(dir, args, flags) },
-  { name: 'list-targets', aliases: ['targets'], run: () => require('./commands/listTargets')() },
-  { name: 'local-dev', aliases: ['localdev'], run: (dir, args, flags) => require('./commands/localDev')(dir, args, flags) },
-  { name: 'connect', aliases: ['login'], run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
+  { name: 'list-targets', run: () => require('./commands/listTargets')() },
+  { name: 'connect', run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
 ];
 
 const aliases = new Map();

package/src/commands/api.js

@@ -6,6 +6,7 @@ const log = require('../logger');
 const { confirm } = require('../prompt');
 const { loadProjectConfig } = require('../projectConfig');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
+const { cachedDescription, normalizeDescription, storeDescription } = require('../apiContractCache');
 
 function readCallInput(projectDir, flags) {
   const raw = flags.input
@@ -66,27 +67,45 @@ async function callOperation(projectDir, operationId, flags = {}) {
   let session;
   let description;
   let input;
+  let config;
   try {
-    const config = loadProjectConfig(projectDir);
+	config = loadProjectConfig(projectDir);
     session = await openToolSession(config, [TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall]);
-    description = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+    description = cachedDescription(projectDir, config.server, operationId);
+    if (!description) {
+      const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+      description = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
+    }
+    if (!description) throw new Error('DraftGo API description is missing contract revision metadata.');
     input = readCallInput(projectDir, flags);
   } catch (error) {
     return printCallError(operationId, error, flags);
   }
-  const destructive = description && (description.destructive === true
-    || description.operation && description.operation.destructive === true);
+  const destructive = description.operation.destructive === true;
   if (destructive && !flags.yes && !flags.y) {
     const approved = await confirm(`Call destructive DraftGo operation ${operationId}?`, { default: false });
     if (!approved) return 0;
   }
   let result;
   try {
-    result = await callStructured(session, TOOL_NAMES.apiCall, {
-      ...input,
-      operation_id: operationId,
-      ...(destructive ? { confirm: true } : {}),
+    const invoke = (contract, confirmed) => callStructured(session, TOOL_NAMES.apiCall, {
+      ...input, operation_id: operationId, registry_revision: contract.registry_revision,
+      ...(confirmed ? { confirm: true } : {}),
     });
+    try {
+      result = await invoke(description, destructive);
+    } catch (error) {
+      if (error.code !== 'CONTRACT_CHANGED') throw error;
+      const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: operationId });
+      description = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
+      if (!description) throw new Error('DraftGo API description is missing contract revision metadata.');
+      const changedDestructive = description.operation.destructive === true;
+      if (changedDestructive && !destructive && !flags.yes && !flags.y) {
+        const approved = await confirm(`Call destructive DraftGo operation ${operationId}?`, { default: false });
+        if (!approved) return 0;
+      }
+      result = await invoke(description, changedDestructive);
+    }
   } catch (error) {
     return printCallError(operationId, error, flags);
   }
@@ -130,6 +149,7 @@ async function apiCommand(projectDir, positional, flags = {}) {
   const result = await callStructured(session, expected, describe
     ? { operation_id: query }
     : { query });
+  if (describe) storeDescription(projectDir, config.server, result);
   if (flags.output === 'json') console.log(JSON.stringify(result, null, 2));
   else printResult(describe ? `DraftGo API ${query}` : `DraftGo API search: ${query}`, result);
   return 0;

package/src/commands/check.js

@@ -1,18 +1,11 @@
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
 const log = require('../logger');
 const { analyzeProject } = require('../projectMap');
 const { inspectRemoteCheckouts } = require('../worktree/status');
 const customServices = require('../customServices');
 const { workspaceHealth } = require('../workspaceHealth');
 
-function legacyCacheDetected(projectDir) {
-  return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
-    .some((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
-}
-
 async function check(projectDir, positional = [], flags = {}) {
   if (!Array.isArray(positional)) {
     flags = positional || {};
@@ -94,7 +87,7 @@ async function check(projectDir, positional = [], flags = {}) {
     workspace_hygiene: hygiene,
   };
   if (flags.output === 'json') {
-    console.log(JSON.stringify({ ...output, legacy_cache_ignored: legacyCacheDetected(projectDir) }, null, 2));
+    console.log(JSON.stringify(output, null, 2));
     return result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
   }
 
@@ -111,8 +104,6 @@ async function check(projectDir, positional = [], flags = {}) {
   if (remote) log.info(`Remote checkout comparison: ${remote.length} resource(s)`);
   for (const message of result.errors) log.err(message);
   for (const detail of result.warningDetails) log.warn(`[${detail.code}/${detail.confidence}] ${detail.message}`);
-  if (legacyCacheDetected(projectDir)) log.dim('  Legacy .draftgo index caches were detected and ignored.');
-
   if (result.errors.length || (flags.strict && result.warnings.length)) return 1;
   log.ok(result.warnings.length ? 'Local checkout validation completed with warnings.' : 'Local checkout validation passed.');
   return 0;

package/src/commands/customService.js

@@ -5,14 +5,12 @@ const log = require('../logger');
 const services = require('../customServices');
 
 function ids(positional) { return positional.map(String).filter(Boolean); }
-const TYPE_ALIASES = new Set(['custom-services', 'custom-service', 'custom_services', 'custom_service', 'services', 'scripts', 'custom_scripts']);
 function isServiceType(value) {
-  return TYPE_ALIASES.has(String(value || '').toLowerCase());
+  return String(value || '').toLowerCase() === 'custom-services';
 }
 function serviceIds(positional) {
   const values = ids(positional);
-  if (isServiceType(values[0])) values.shift();
-  return values;
+  return isServiceType(values[0]) ? values.slice(1) : [];
 }
 function output(flags, value) {
   if (flags.output === 'json') console.log(JSON.stringify(value, null, 2));

package/src/commands/delete.js

@@ -6,23 +6,7 @@ const log = require('../logger');
 const { confirm } = require('../prompt');
 const { loadProjectConfig } = require('../projectConfig');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
-
-const LEGACY_TYPES = new Set([
-  'page', 'pages', 'nav', 'navigation', 'navigations', 'doc', 'docs', 'article',
-  'db_meta', 'custom_scripts', 'doc_categories', 'aihub', 'roles', 'users', 'system_config',
-]);
-
-function resultItems(value) {
-  if (Array.isArray(value)) return value;
-  if (!value || typeof value !== 'object') return [];
-  if (Array.isArray(value.items)) return value.items;
-  if (Array.isArray(value.operations)) return value.operations;
-  return value.data ? resultItems(value.data) : [];
-}
-
-function operationId(value) {
-  return value && (value.operation_id || value.operationId || value.id);
-}
+const { cachedDescription, normalizeDescription, storeDescription } = require('../apiContractCache');
 
 function readParams(projectDir, flags) {
   const raw = flags.params ? String(flags.params)
@@ -45,40 +29,25 @@ function pathParameterName(description) {
 async function deleteResource(projectDir, positional, flags = {}) {
   if (!positional.length && !flags['operation-id']) {
     log.err('Usage: draftgo delete <operation_id> [id] [--params JSON]');
-    log.dim('  Legacy form is supported when discovery is unambiguous: draftgo delete <type> <id>.');
     return 1;
   }
   const config = loadProjectConfig(projectDir);
   const session = await openToolSession(config, [
-    TOOL_NAMES.apiSearch, TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall,
+    TOOL_NAMES.apiDescribe, TOOL_NAMES.apiCall,
   ]);
 
-  const first = String(positional[0] || '');
-  const legacy = LEGACY_TYPES.has(first.toLowerCase()) && !flags['operation-id'];
-  let selectedOperation = flags['operation-id'] ? String(flags['operation-id']) : (legacy ? null : first);
-  const resourceId = legacy ? positional[1] : positional[1];
-  if (legacy) {
-    if (!resourceId) {
-      log.err('Legacy delete form requires a resource id.');
-      return 1;
-    }
-    const search = await callStructured(session, TOOL_NAMES.apiSearch, { query: `delete ${first}` });
-    const candidates = resultItems(search).filter((item) => operationId(item)
-      && (!item.method || String(item.method).toUpperCase() === 'DELETE'));
-    if (candidates.length !== 1) {
-      log.err(`Delete operation discovery was ambiguous (${candidates.length} matches).`);
-      log.dim(`  Run \`draftgo api delete ${first}\`, then pass --operation-id explicitly.`);
-      return 1;
-    }
-    selectedOperation = operationId(candidates[0]);
-  }
+  const selectedOperation = flags['operation-id'] ? String(flags['operation-id']) : String(positional[0]);
+  const resourceId = positional[1];
 
-  const description = await callStructured(session, TOOL_NAMES.apiDescribe, {
-    operation_id: selectedOperation,
-  });
+  let contract = cachedDescription(projectDir, config.server, selectedOperation);
+  if (!contract) {
+    const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: selectedOperation });
+    contract = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
+  }
+  if (!contract) throw new Error('DraftGo API description is missing contract revision metadata.');
   const params = readParams(projectDir, flags);
   if (resourceId && Object.keys(params).length === 0) {
-    const parameterName = pathParameterName(description);
+    const parameterName = pathParameterName(contract.operation);
     if (!parameterName) {
       log.err('The operation does not expose exactly one path parameter; provide --params JSON explicitly.');
       return 1;
@@ -89,11 +58,19 @@ async function deleteResource(projectDir, positional, flags = {}) {
     const approved = await confirm(`Call destructive DraftGo operation ${selectedOperation}?`, { default: false });
     if (!approved) return 0;
   }
-  const result = await callStructured(session, TOOL_NAMES.apiCall, {
-    ...params,
-    operation_id: selectedOperation,
-    confirm: true,
+  const invoke = () => callStructured(session, TOOL_NAMES.apiCall, {
+    ...params, operation_id: selectedOperation, registry_revision: contract.registry_revision, confirm: true,
   });
+  let result;
+  try {
+    result = await invoke();
+  } catch (error) {
+    if (error.code !== 'CONTRACT_CHANGED') throw error;
+    const described = await callStructured(session, TOOL_NAMES.apiDescribe, { operation_id: selectedOperation });
+    contract = storeDescription(projectDir, config.server, described) || normalizeDescription(described);
+    if (!contract) throw new Error('DraftGo API description is missing contract revision metadata.');
+    result = await invoke();
+  }
   if (flags.output === 'json') console.log(JSON.stringify(result, null, 2));
   else log.ok(`DraftGo operation completed: ${selectedOperation}`);
   return 0;

package/src/commands/deploy.js

@@ -23,7 +23,7 @@ async function deploy(projectDir, positional, flags = {}) {
 
   const [resourceType, ...ids] = positional;
   if (!resourceType || !ids.length) {
-    log.err('Deploy no longer commits every legacy index. Specify <pages|nav|docs> <id...>.');
+    log.err('Usage: draftgo deploy <pages|nav|docs> <id...> --delivery preview|deploy');
     return 1;
   }
   if (delivery === 'preview') {