@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/contracts/verbs.schema.json

@@ -0,0 +1,2539 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://whyshu.com/argent/0.3/verbs.schema.json",
+  "title": "Argent 0.3 verb 契约（输入/输出 Schema）",
+  "description": "宿主（CLI/MCP/未来 agent）只依赖本文件；改契约须同步跑 scripts/tests/argent-contracts.test.mjs。",
+  "type": "object",
+  "exitCodes": {
+    "0": {
+      "meaning": "成功（含「成功但空」）",
+      "when": "认领/查询/回写成功；flow claim 无票可认领（ok:true, empty:true）；查询无匹配行",
+      "action": "正常：有结果就用；empty:true 即本轮无事，不重试、不告警"
+    },
+    "1": {
+      "meaning": "运行失败（含被拒 FAIL）",
+      "when": "回写守卫拒绝、源读取失败、许可拒绝（超宽限/未授权）、内部错误",
+      "action": "按 reason 处置（落卡/重试/请人）；不得当成功继续"
+    },
+    "2": {
+      "meaning": "用法错误（参数/缺声明/环境不可用）",
+      "when": "未知 verb、缺必填参数、注册表里没这条流程（缺声明）、解释器不可用（python_unavailable）",
+      "action": "不要重试：读 reason 改参数或补环境，再把结论上报给人"
+    },
+    "3": {
+      "meaning": "仅 = 许可宽限放行",
+      "when": "check-license / lease --check 命中宽限期：业务放行但授权已过期",
+      "action": "继续跑业务（不停摆），同时必须上报「许可在宽限期内」"
+    },
+    "$comment": "A1 唯一口径（D4 裁定，2026-10-03）：`$?` 即结论，不需要 grep 文案。0/1/2/3 四义不得复用。",
+    "reserved": {
+      "note": "3 不得用于其它语义；2 不得再被用作「有告警/部分成功/需要人工看一眼」。被包脚本（scripts/*.py）的退出码不在本表管辖内 —— 「脚本退出码 → verb 退出码」的翻译是 core/cli 适配层的职责（先例：flow_claim.py 的 3 = 无票 ⇒ 翻成 0 + empty:true）。"
+    }
+  },
+  "jsonContract": {
+    "$comment": "A2 唯一口径：`--json` 机器可读、默认人类可读。",
+    "minimal": {
+      "ok": "恒必填。true = 本次调用按判据完成（成功或许可宽限放行）；false = 失败/被拒。**ok:true 不代表有结果**",
+      "empty": "列表/认领/查询类 verb 必填。true = 成功但结果为空（「没票要跑」是正常态，不是错误）",
+      "code": "ok:false 时必填；3 放行时也带。**必须等于进程退出码**（$? == (json.code ?? 0)）",
+      "reason": "ok:false 与 empty:true 时必填。机器可判的短码（词表 = argent.contracts.json#reasonCodes）；禁止拿中文句子当判据（人话放 error/note）"
+    },
+    "truthTable": [
+      "empty:true ⇒ ok:true ∧ code ∈ {0,3}",
+      "ok:false ⇒ code ≥ 1",
+      "code:3 ⇒ 只可能是许可宽限",
+      "只有 ok:true ∧ empty:false 才允许产出业务动作"
+    ],
+    "stdout": "--json 时 stdout 只有一份 JSON（诊断/告警/进度一律 stderr）——否则宿主 JSON.parse 会崩",
+    "echo": "凡带过滤或截断参数（--flow/--tail/--status…）的 verb，输出必须回显**实际生效值**（未过滤写 null，不写空串）；空结果必须能一眼分出「真没有」与「被过滤/被截断掉了」"
+  },
+  "dryRunContract": {
+    "$comment": "A3 唯一口径：写类 verb 的默认安全态。",
+    "rule": "凡 write 类 verb 必须支持 --dry-run，且**默认即 dry-run**；真写要显式确权（--apply / --confirm / --yes）",
+    "zeroSideEffects": [
+      "台账 JSONL（flow-ledger.jsonl）不新增",
+      "租约/锁文件不新增（数据目录内零新文件）",
+      "备份目录（invoice-writeback/backup/）不新增",
+      "审计 JSONL（audit.jsonl / license-gate.jsonl / env-writeback/audit.jsonl）不新增",
+      "远程表/附件不写",
+      "通知不投递（含 .pushed-* 标记不落）",
+      "紫鸟店铺缓存（ziniao-stores.json / ziniao-store-ips.json）不落"
+    ],
+    "samePath": "dry-run 与真跑共用**同一条判据路径**（守卫照跑，只是最后不落盘），输出带 dryRun:true + 「将要做什么」的预览（目标记录/字段/命令）",
+    "judge": "判据 = 跑两次 dry-run 后数据目录逐字节不变；「预演也留痕」= 违规",
+    "pending": "license install/renew/**activate** 已落地（默认 dry-run + 零副作用断言；activate 另加\"零网络请求\"断言，2026-10-04）；剩 env write / report｜notify 通道（P2）。"
+  },
+  "verbs": {
+    "version": {
+      "name": "version",
+      "args": [],
+      "exitCodes": [
+        0
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb（不发包、不落盘）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "argent",
+          "dsh"
+        ],
+        "echo": [],
+        "optional": [
+          "billingMode"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": true,
+        "note": "恒 ok:true；无列表语义故无 empty"
+      },
+      "in": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok",
+          "argent"
+        ],
+        "properties": {
+          "ok": {
+            "const": true
+          },
+          "argent": {
+            "type": "string"
+          },
+          "dsh": {
+            "type": "string"
+          }
+        }
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ]
+    },
+    "sop": {
+      "name": "sop",
+      "args": [
+        "--flow"
+      ],
+      "exitCodes": [
+        0,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "flow"
+        ],
+        "echo": [
+          "flow"
+        ],
+        "optional": [
+          "role",
+          "capability",
+          "promptPath",
+          "matchedBy",
+          "skillDir",
+          "pitfalls",
+          "code",
+          "reason",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": false,
+        "pending": "成功路径无 empty（该流程有没有 SOP）；失败路径已合规（code/reason，D2/D3 已修）⇒ P1 后续批次收口"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "flow",
+          "role"
+        ],
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "role": {
+            "type": "string"
+          },
+          "capability": {
+            "type": "string"
+          },
+          "promptPath": {
+            "type": "string"
+          },
+          "matchedBy": {
+            "enum": [
+              "capability",
+              "localId",
+              "role",
+              "none"
+            ]
+          },
+          "skillDir": {
+            "type": "string"
+          },
+          "pitfalls": {
+            "type": "boolean"
+          }
+        }
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ]
+    },
+    "source": {
+      "name": "source",
+      "args": [
+        "--flow",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb（拉源不写）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok"
+        ],
+        "passthrough": [
+          "output"
+        ],
+        "echo": [
+          "flow"
+        ],
+        "optional": [
+          "code",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": false,
+        "pending": "输出仍是 output 字符串（被包脚本 JSON 未拆封）⇒ P1 后续批次收口为 A2（注意 cases 为空是合法结论，届时必须 empty:true）"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "json": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        }
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "flow": {
+      "name": "flow",
+      "group": true,
+      "subcommands": [
+        "claim",
+        "triage",
+        "list"
+      ],
+      "args": [],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "note": "随子命令：`flow claim` 默认 dry-run；`flow triage` 只读"
+      },
+      "jsonFields": {
+        "delegatesTo": [
+          "claim",
+          "triage"
+        ],
+        "note": "信封与退出码逐字取子命令（不另立一套）",
+        "subcommandA2": {
+          "list": {
+            "compliant": true,
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "emptyCapable": true,
+            "reasonWhenEmpty": "no_match",
+            "echo": [
+              "sources",
+              "sourceCount",
+              "since",
+              "sinceInput",
+              "tail",
+              "scanned",
+              "matched",
+              "returned",
+              "perSource",
+              "dataDir"
+            ],
+            "note": "`flow list` **没有同名顶层 verb**（它是组里的子命令）⇒ 形状声明在这里，由 argent-contracts.test.mjs 的组 verb 检查逐子命令核对；实现在 core/lib/flow-list.mjs"
+          },
+          "note": "给\"没有同名顶层 verb\"的子命令声明 A2 形状（有同名 verb 的子命令由 delegatesTo 覆盖）；**两处必须都能核到 compliant:true**"
+        }
+      },
+      "a2": {
+        "compliant": true,
+        "note": "组 verb：本身不产 JSON，只做子命令分派（未知子命令 ⇒ code 2 + reason unknown_subcommand）"
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "claim": {
+      "name": "claim",
+      "args": [
+        "--flow",
+        "--max",
+        "--lease-min",
+        "--batch",
+        "--per-ip",
+        "--ledger",
+        "--lock",
+        "--cases-from-dir",
+        "--apply",
+        "--confirm",
+        "--plan-only",
+        "--json",
+        "--dry-run"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "confirmFlags": [
+          "--apply",
+          "--confirm"
+        ],
+        "note": "⛔ 被包脚本 scripts/flow_claim.py 的退出码 3（无票）由适配层翻成 0 + empty:true；出现 --dry-run 即恒 dry-run（调用方说了算）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "flow",
+          "flowPrefix",
+          "flowKnown",
+          "max",
+          "leaseMin",
+          "batch",
+          "perIp",
+          "dryRun",
+          "casesFromDir"
+        ],
+        "optional": [
+          "claimed",
+          "count",
+          "ledger",
+          "lock",
+          "planOnly",
+          "note",
+          "error"
+        ],
+        "emptyCapable": true,
+        "reasonWhenEmpty": "no_ticket"
+      },
+      "a2": {
+        "compliant": true,
+        "note": "本轮（P1 首批）落地：$? == json.code；--json 时 stdout 只有一份 JSON"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "max": {
+            "type": "number"
+          },
+          "leaseMin": {
+            "type": "number"
+          },
+          "batch": {
+            "type": "number"
+          },
+          "perIp": {
+            "type": "number"
+          },
+          "ledger": {
+            "type": "string"
+          },
+          "lock": {
+            "type": "string"
+          },
+          "casesFromDir": {
+            "type": "string"
+          },
+          "apply": {
+            "type": "boolean"
+          },
+          "confirm": {
+            "type": "boolean"
+          },
+          "planOnly": {
+            "type": "boolean"
+          },
+          "dryRun": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok",
+          "empty",
+          "code"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "flow": {
+            "type": "string"
+          },
+          "flowPrefix": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "dryRun": {
+            "type": "boolean"
+          },
+          "casesFromDir": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ],
+      "licenseGate": {
+        "enforced": true,
+        "when": "真写路径（确权参数出现且非 --dry-run）；dry-run/只读不查（不打扰、也不污染证据）",
+        "mode": "ARGENT_LICENSE_ENFORCE：off（不查）｜observe（**默认**：只留证据、不拦）｜enforce（不可用 ⇒ 拒绝写）",
+        "judgedBy": "scripts/license-gate.mjs（← core/lib/license-verdict.mjs ← scripts/check-license.mjs）——**调既有模块，不复制判据**",
+        "adapter": "core/lib/license-guard.mjs",
+        "cap": "从注册表解析（`<flow>.capability`，与 flow_config.py --get capability 同源）；解析不到 ⇒ 以流程名当能力并如实标注",
+        "evidence": "$ARGENT_DATA_DIR/license-gate.jsonl 每次判定一行（observe 也留，decision=would_block）",
+        "denied": {
+          "code": 1,
+          "reason": "license_denied",
+          "effect": "整体拒绝 + **零副作用**（不写台账/不落盘/不回写）"
+        },
+        "grace": {
+          "code": 3,
+          "reason": "license_grace",
+          "effect": "照常执行但必须上报（A1：3 只表示许可宽限放行）"
+        },
+        "gateError": {
+          "code": 0,
+          "reason": "gate_error",
+          "effect": "闸门自己跑不起来 ⇒ 放行 + 响亮告警（宁可不拦，不可误停；与 flow-trigger.sh 同口径）"
+        },
+        "capSource": "注册表 flows.<canonical>.capability（P2a 起规范 id = <业务线>.<流程>）"
+      },
+      "exitCodesNote": "0 认领成功/dry-run ｜ 2 用法 ｜ 1 失败或被拒（含 license_denied）。**许可宽限时返回 3**（见 licenseGate.grace；退出码表里的 3 由 license verb 声明）"
+    },
+    "triage": {
+      "name": "triage",
+      "args": [
+        "--flow",
+        "--cases-from-dir",
+        "--ledger",
+        "--limit",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "note": "只读 verb：只出计划、不落台账（旧 `claim` 行为逐字保留）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "flow",
+          "flowPrefix",
+          "flowKnown",
+          "limit",
+          "casesFromDir"
+        ],
+        "optional": [
+          "counts",
+          "notes",
+          "plan",
+          "error"
+        ],
+        "emptyCapable": true,
+        "reasonWhenEmpty": "no_ticket"
+      },
+      "a2": {
+        "compliant": true,
+        "note": "本轮（P1 首批）落地：旧 `claim` 的分诊行为，形状按 A2 收口"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "casesFromDir": {
+            "type": "string"
+          },
+          "ledger": {
+            "type": "string"
+          },
+          "limit": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok",
+          "empty",
+          "code"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "flow": {
+            "type": "string"
+          },
+          "flowPrefix": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "dryRun": {
+            "type": "boolean"
+          },
+          "casesFromDir": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "gap": {
+      "name": "gap",
+      "args": [
+        "--flow",
+        "--ticket"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb"
+      },
+      "jsonFields": {
+        "always": [
+          "ok"
+        ],
+        "passthrough": [
+          "output"
+        ],
+        "echo": [
+          "flow"
+        ],
+        "optional": [
+          "code",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": false,
+        "pending": "与 source 同病（output 字符串）⇒ P1 后续批次收口"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "ticket": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        }
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "writeback": {
+      "name": "writeback",
+      "args": [
+        "--record-id",
+        "--allow-record",
+        "--file",
+        "--status",
+        "--force",
+        "--yes",
+        "--dry-run",
+        "--json",
+        "--text-only",
+        "--replace"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "confirmFlags": [
+          "--yes"
+        ],
+        "note": "真写需 --yes（或 --write）；--dry-run 恒优先"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "dryRun"
+        ],
+        "echo": [
+          "recordId",
+          "allowRecord",
+          "status",
+          "file",
+          "dryRun"
+        ],
+        "optional": [
+          "code",
+          "outTail",
+          "reason",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": false,
+        "pending": "缺 empty/code/reason 的完整最小集（回写守卫被拒时只有 outTail 文本）⇒ P1 后续批次收口"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "recordId": {
+            "type": "string"
+          },
+          "allowRecord": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          },
+          "confirm": {
+            "type": "boolean"
+          },
+          "dryRun": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "recordId",
+          "allowRecord"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok",
+          "dryRun"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "dryRun": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "outTail": {
+            "type": "string"
+          }
+        }
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ],
+      "licenseGate": {
+        "enforced": true,
+        "when": "真写路径（确权参数出现且非 --dry-run）；dry-run/只读不查（不打扰、也不污染证据）",
+        "mode": "ARGENT_LICENSE_ENFORCE：off（不查）｜observe（**默认**：只留证据、不拦）｜enforce（不可用 ⇒ 拒绝写）",
+        "judgedBy": "scripts/license-gate.mjs（← core/lib/license-verdict.mjs ← scripts/check-license.mjs）——**调既有模块，不复制判据**",
+        "adapter": "core/lib/license-guard.mjs",
+        "cap": "从注册表解析（`<flow>.capability`，与 flow_config.py --get capability 同源）；解析不到 ⇒ 以流程名当能力并如实标注",
+        "evidence": "$ARGENT_DATA_DIR/license-gate.jsonl 每次判定一行（observe 也留，decision=would_block）",
+        "denied": {
+          "code": 1,
+          "reason": "license_denied",
+          "effect": "整体拒绝 + **零副作用**（不写台账/不落盘/不回写）"
+        },
+        "grace": {
+          "code": 3,
+          "reason": "license_grace",
+          "effect": "照常执行但必须上报（A1：3 只表示许可宽限放行）"
+        },
+        "gateError": {
+          "code": 0,
+          "reason": "gate_error",
+          "effect": "闸门自己跑不起来 ⇒ 放行 + 响亮告警（宁可不拦，不可误停；与 flow-trigger.sh 同口径）"
+        },
+        "flow": "wenyao-invoice（该回写器服务的流程；可用 --flow 覆盖）"
+      },
+      "exitCodesNote": "同 claim：0 成功/dry-run ｜ 2 用法 ｜ 1 被拒；许可宽限时返回 3（见 licenseGate.grace）"
+    },
+    "report": {
+      "name": "report",
+      "args": [
+        "--error",
+        "--flow",
+        "--attempt",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "P2 的 notify 通道逐个补（§P0-A A3 现状行）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok"
+        ],
+        "passthrough": [
+          "output"
+        ],
+        "echo": [
+          "flow",
+          "attempt"
+        ],
+        "optional": [
+          "classified",
+          "code",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": false,
+        "pending": "P2（通知通道 + 幂等 + dry-run）统一收口"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "minLength": 1
+          },
+          "attempt": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "error"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "classified": {
+            "type": "object"
+          }
+        }
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ]
+    },
+    "ledger": {
+      "name": "ledger",
+      "args": [
+        "--flow",
+        "--tail",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb（台账查询永不写）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason",
+          "flow",
+          "flowPrefix",
+          "tail",
+          "matched",
+          "count",
+          "rows"
+        ],
+        "echo": [
+          "flow",
+          "flowPrefix",
+          "tail",
+          "flowKnown",
+          "matched"
+        ],
+        "optional": [
+          "flowKnown",
+          "note",
+          "error"
+        ],
+        "emptyCapable": true,
+        "reasonWhenEmpty": "no_match",
+        "emptyJudge": "count === 0 ⇒ empty:true（且必须回显 matched/tail 供分辨「真没有」与「被过滤/被截断」）"
+      },
+      "a2": {
+        "compliant": true,
+        "note": "本轮（P1 前置④）补 empty/code/reason，让 A2 真值表在 ledger 上判得出来"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "tail": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 200
+          }
+        },
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok",
+          "empty",
+          "code",
+          "count",
+          "rows"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "flow": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "flowPrefix": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "flowKnown": {
+            "type": [
+              "boolean",
+              "null"
+            ]
+          },
+          "tail": {
+            "type": "number"
+          },
+          "matched": {
+            "type": "number"
+          },
+          "count": {
+            "type": "number"
+          },
+          "rows": {
+            "type": "array"
+          }
+        }
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ]
+    },
+    "license": {
+      "name": "license",
+      "kind": "group",
+      "subcommands": {
+        "status": {
+          "args": [
+            "--file",
+            "--cap",
+            "--vertical",
+            "--now",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            3,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只读：不写任何文件"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "licenseFile",
+              "state",
+              "licenseReason",
+              "expiresAt",
+              "issuedAt",
+              "graceDays",
+              "graceUntil",
+              "inGrace",
+              "graceSource",
+              "requestedCaps",
+              "requestedVertical",
+              "device"
+            ],
+            "optional": [
+              "userId",
+              "seats",
+              "capabilities",
+              "verticals",
+              "gateReason",
+              "conclusion",
+              "warnings",
+              "error"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": true,
+            "note": "透传 `scripts/check-license.mjs --json`（判定点唯一在 CLI 进程内）；`$? == json.code`"
+          },
+          "note": "无许可文件 ⇒ `state:\"denied\"` + `reason:\"missing\"` + exit 1（§3.5③ 的验收行）；宽限 ⇒ exit 3（`reason:\"license_grace\"`）"
+        },
+        "verify": {
+          "args": [
+            "--file",
+            "--secret-file",
+            "--now",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            3,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只验不写（落盘是 install 的事）"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "licenseFile",
+              "state",
+              "signature",
+              "device",
+              "expiresAt",
+              "graceDays",
+              "graceUntil",
+              "graceSource",
+              "inGrace"
+            ],
+            "optional": [
+              "userId",
+              "seats",
+              "capabilities",
+              "verticals",
+              "warnings",
+              "error"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": true,
+            "note": "判定走 `core/lib/license-verdict.mjs`（与 status 同源）；显式 `--file` 不存在 ⇒ 2（用法），缺省路径不存在 ⇒ 1 + missing"
+          }
+        },
+        "install": {
+          "args": [
+            "--file",
+            "--secret-file",
+            "--rebind",
+            "--apply",
+            "--yes",
+            "--confirm",
+            "--dry-run",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": true,
+            "default": true,
+            "confirmFlags": [
+              "--apply",
+              "--yes",
+              "--confirm"
+            ],
+            "note": "真写要显式确权；`--dry-run` 恒优先。**dry-run 零持久副作用**：不落许可、不备份、不写重绑计数。透传 `scripts/install-license.mjs` 的 0/1/2"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "dryRun",
+              "applied",
+              "licenseFile",
+              "targetFile",
+              "device",
+              "expiresAt",
+              "graceDays",
+              "graceUntil",
+              "inGrace"
+            ],
+            "optional": [
+              "source",
+              "target",
+              "userId",
+              "capabilities",
+              "verticals",
+              "seats",
+              "backups",
+              "rebind",
+              "secretInstalled",
+              "verifiedAfterInstall",
+              "mode",
+              "warnings",
+              "error"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": true,
+            "note": "设备不匹配 ⇒ exit 1 + `reason:\"device_mismatch\"` **且不落盘**；自助重绑用尽 ⇒ `reason:\"rebind_exhausted\"`"
+          }
+        },
+        "request": {
+          "args": [
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只读（打印设备码，不写任何文件；连跑两次同一码）"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "device",
+              "license",
+              "rebind",
+              "fingerprint"
+            ],
+            "optional": [
+              "warnings",
+              "error"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": true,
+            "note": "指纹**只认 IOPlatformUUID**（D3）；读不到 ⇒ exit 2 + `reason:\"device_unsupported\"`/`\"device_read_failed\"`，**不误判为拒绝**"
+          }
+        },
+        "renew": {
+          "args": [
+            "--file",
+            "--secret-file",
+            "--apply",
+            "--yes",
+            "--confirm",
+            "--dry-run",
+            "--online",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            3,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": true,
+            "default": true,
+            "confirmFlags": [
+              "--apply",
+              "--yes",
+              "--confirm"
+            ],
+            "note": "`--file` 时与 install 同一条路（默认 dry-run）；无 `--file` 时**不写任何文件**"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "licenseFile",
+              "state",
+              "expiresAt",
+              "graceDays",
+              "graceUntil",
+              "inGrace",
+              "device",
+              "refresh"
+            ],
+            "optional": [
+              "dryRun",
+              "applied",
+              "targetFile",
+              "rebind",
+              "backups",
+              "warnings",
+              "error"
+            ],
+            "emptyCapable": true,
+            "reasonWhenEmpty": "no_refresh_source"
+          },
+          "a2": {
+            "compliant": true,
+            "note": "没有新许可文件 ⇒ **成功但空**（`ok:true, empty:true, code:0, reason:\"no_refresh_source\"`）——**绝不**把“没刷新成功”当 denied（§3.5① 纪律 2）"
+          }
+        },
+        "explain": {
+          "args": [
+            "--file",
+            "--cap",
+            "--vertical",
+            "--now",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            3,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只读：只重组 check-license 的既有字段"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "state",
+              "licenseFile",
+              "expiresAt",
+              "graceDays",
+              "graceUntil",
+              "inGrace",
+              "graceSource",
+              "device",
+              "missing",
+              "next",
+              "limitation"
+            ],
+            "optional": [
+              "whatIsMissing",
+              "warnings",
+              "conclusion",
+              "error"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": true,
+            "note": "与 status **同源**（无第二份判据）；`limitation` 必须如实说明 `device` 未进签名、重绑是礼貌上限（§3.6③）"
+          }
+        },
+        "activate": {
+          "args": [
+            "--code",
+            "--code-file",
+            "--server",
+            "--device-code",
+            "--no-device",
+            "--secret-file",
+            "--instance",
+            "--intent",
+            "--apply",
+            "--yes",
+            "--confirm",
+            "--dry-run",
+            "--allow-regression",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": true,
+            "default": true,
+            "confirmFlags": [
+              "--apply",
+              "--yes",
+              "--confirm"
+            ],
+            "note": "**默认 dry-run**：不发任何网络请求、不写任何文件（连审计都不落）—— dry-run 只打印\"将请求哪个端点、将写哪个文件\"；真兑换要显式 --apply/--yes/--confirm，`--dry-run` 恒优先。真兑换仍走 install-license.mjs 的落盘判据。"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "dryRun",
+              "applied",
+              "server",
+              "endpoint",
+              "codePrefix",
+              "request",
+              "redemption",
+              "audit"
+            ],
+            "optional": [
+              "install",
+              "signatureVersion",
+              "deviceSigned",
+              "unchanged",
+              "allowRegression",
+              "regressionReleased",
+              "device",
+              "comparison",
+              "renewal",
+              "backups",
+              "userId",
+              "seats",
+              "capabilities",
+              "verticals",
+              "expiresAt",
+              "graceDays",
+              "licenseFile",
+              "targetFile",
+              "would",
+              "next",
+              "error",
+              "hint",
+              "serverReason",
+              "warnings"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": true,
+            "note": "A2：`ok/empty/code/reason` 恒在、`$? == json.code`、`--json` 时 stdout 只有一份 JSON；回显 `server/endpoint/codePrefix/request.device/request.target`（A2 的\"实际生效值\"）。**明文码绝不出现在任何输出/审计里**（只回显前 8 位 codePrefix）——`scripts/tests/license-activate.test.mjs` 对每条路径断言\"搜不到码的任意 ≥12 位片段\"。`request.allowRegression` / `allowRegression`（是否带了逃生阀）与 `regressionReleased`（它是否**真的**放行了一次倒退，带标志但没倒退 ⇒ false）分两个字段，避免把\"签了字\"读成\"倒退过\"。"
+          },
+          "note": "A1：`0` 兑换并落盘成功（含\"与现役逐字节一致 ⇒ 未改动\"）｜`2` 用法/环境（码形态非法 / **未配置端点** / 非 TLS 且非回环 / 设备码形状非法 / 读不到本机设备码）｜`1` 兑换被拒（服务端错误码同名映射、网络不可达或超时、产物验签不过/设备不匹配/倒退被拒）。**不占退出码 3**（3 只表示许可宽限放行）。落盘判据 = `scripts/install-license.mjs`（本层不自己写盘）。`--server` 只给 **base URL**（正确值 `https://whyshu.com` ⇒ 拼出 `https://whyshu.com/api/argent/license/redeem`；写成 `…/api/argent` 会多一层前缀 ⇒ 404）。倒退被拒（`regression_refused`）的逃生阀 = 显式 `--allow-regression`（**只透传**给 install-license，本层不复制判据；放行时 human 显式标注\"本次放行了一次倒退\"）。"
+        },
+        "ops": {
+          "args": [
+            "--from",
+            "--server",
+            "--token-file",
+            "--local",
+            "--probe",
+            "--days",
+            "--now",
+            "--device",
+            "--filter",
+            "--prefix",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只读：**零副作用**（不写任何集合/文件/审计；HTTP 只发 GET，⛔ 绝不调 `POST /api/argent/license/release-device`） ⇒ 没有 `--apply`/`--yes`，JSON 里以 `readOnly:true` + `sideEffects:\"none\"` 表达（**不写** `dryRun`）。"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "subcommand",
+              "readOnly",
+              "sideEffects",
+              "mode",
+              "source",
+              "dataDir",
+              "now",
+              "days",
+              "inflight",
+              "failures",
+              "timeline",
+              "seats",
+              "anomalies",
+              "coverage",
+              "coverageDetail",
+              "missingEndpoints",
+              "unavailable",
+              "definition"
+            ],
+            "optional": [
+              "filters",
+              "since",
+              "fieldProfile",
+              "prefixes",
+              "prefixSource",
+              "probe",
+              "device",
+              "local",
+              "endpoints",
+              "judgedBy",
+              "warnings",
+              "error",
+              "usage"
+            ],
+            "emptyCapable": true,
+            "reasonWhenEmpty": "no_match"
+          },
+          "a2": {
+            "compliant": true,
+            "note": "回显**实际生效值**：`mode`（snapshot｜server｜local）/ `now` / `days` / `filters` / 每节的 `available`；每节不可用时给 `reason` + `needs`，`missingEndpoints` 列出缺的服务端**只读**接口（= 静态登记 `exists:false` **∪ 本轮实测 404**，后者正是「接口已就绪但未部署」这个窗口的证据）；顶层 `coverage`/`coverageDetail` 一眼可判「这份视图是不是全的」（`full` ⇔ 每个可用节都 full 且没有缺席的节）。 ⛔ 缺数据一律 `available:false`，**绝不用 0 充数**（那正是\"按 `status` 查恒空\"的假绿形态）；⛔ **一节都答不了时 `empty:false`**（不是 `no_match`）。凭证只从 0600 的文件读、绝不回显（`source.token` 恒为占位串）。"
+          },
+          "note": "A1：`0` 读成功（含\"成功但空\" `empty:true + no_match`）｜`2` 用法/环境（未知参数、`--from` 与 `--server`/`--local` 同时给、快照不可解析、**缺域必需字段 `field_missing`**、端点未配置、缺 token、token 文件权限不是 0600；**以及服务端只读接口的业务性拒绝：`field_unknown`（`?status=`）/`rate_limited`（6 次/分）/`method_not_allowed`（405）/`admin_required`（401/403）/`bad_request`（400 `bad_*`）**）｜`1` 数据源读失败（服务端连不上/超时、响应不合约）。**不占退出码 3**。 两个已知陷阱（O2）在这里是**响亮失败**：码状态字段是 `state` **不是** `status`；席位**不是**存储字段 `used`（= `seats` + `deviceLimit`（缺省跟随 seats）+ `releasedAt` 为空的设备码去重数）⇒ 用错字段一律 exit 2 `field_missing`，**不静默返回 0**。 每节不可用时的**节级** `reason` 取值（宿主可分支，唯一真源 = `core/lib/license-ops.mjs#OPS_SECTION_REASONS`）：`endpoint_missing`（服务端没这个只读接口 —— 含**实测 404** 的「已就绪但未部署」）/`needs_server`（本机产物答不了）/`no_prefix`（没有可查的前缀）/`no_data`（快照里没有这个集合 —— 缺席 ≠ 为空）。 服务端**只读**接口：`activation-codes`（`?state=issued,redeeming,revoked&limit=200`）/ `events`（`?since=&limit=200`）/ `seats`（`?limit=200`）/ `devices/{codePrefix}`（= 全量在途码 / 事件投影 / 席位账目 / 设备归属），与既有 `activation-code/{prefix}` 共 5 条，⛔ 一律只发 GET；写端点（`POST /release-device`）**不入登记表、不探测、不调用**。 ⚠️ 四处字段映射（服务端契约 §5）：① `seats.devices[].codePrefix → accounts[].devices[].code`（12 位前缀，⛔ **不补 64hex 全码**）② `seats.items/totals → principals/totals`，`deviceLimitSource` 机器值（`deviceLimit`｜`seats`）→ 展示串由客户端拼③ `device.found = 服务端 total`（`empty:true ⇔ total === 0`，查无此码是**空集**不是 404）④ `timeline.scanned = 服务端 total`（窗口内）/`count` = 本页。"
+        }
+      },
+      "args": [
+        "status",
+        "verify",
+        "install",
+        "request",
+        "renew",
+        "explain",
+        "activate",
+        "ops"
+      ],
+      "exitCodes": [
+        0,
+        3,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "confirmFlags": [
+          "--apply",
+          "--yes",
+          "--confirm"
+        ],
+        "note": "随子命令：install/renew/**activate** 是写类 ⇒ **默认 dry-run**；status/verify/request/explain 只读。`--dry-run` 恒优先（调用方说了算）；activate 的 dry-run 还额外保证\"**零网络请求**\"（不探测、不占用一次性码）。 `ops` 是**只读**（零副作用，没有 --apply）。"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "subcommand"
+        ],
+        "optional": [
+          "licenseFile",
+          "state",
+          "expiresAt",
+          "graceDays",
+          "device",
+          "error"
+        ],
+        "emptyCapable": true
+      },
+      "a2": {
+        "compliant": true,
+        "note": "P1 第二批落地（此前恒 `ok:true`/exit 0，见 §2.2④）；子命令逐个达标，退出码 0/3/1/2 与 `check-license.mjs` 同源"
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ]
+    },
+    "doctor": {
+      "name": "doctor",
+      "args": [
+        "--customer",
+        "--flow",
+        "--online",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb：两种形态都不写任何文件/凭据/settings，不建目录、不真发通知（--customer 形态的零副作用清单见 subforms.customer）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok"
+        ],
+        "passthrough": [
+          "output"
+        ],
+        "echo": [
+          "flow",
+          "online"
+        ],
+        "optional": [
+          "code",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": false,
+        "note": "**分档**：`--customer` 子形态 A2 合规（见 subforms.customer.a2，实测 `$? == json.code`）；`--flow <id>` 形态仍是 `scripts/flow_preflight.py` 的转发（passthrough output），合规性待收口",
+        "pending": "`doctor --flow` 形态：按 D4 用 0 + JSON 标记承载 WARN（被包脚本 flow_preflight.py 的退出码不在本批改）"
+      },
+      "in": {
+        "$comment": "顶层 in 描述**默认（--flow）形态**；`--customer` 形态的入参见 subforms.customer.in",
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "customer": {
+                "type": "boolean",
+                "const": true
+              },
+              "json": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "customer"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "flow": {
+                "type": "string"
+              },
+              "online": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "flow"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      },
+      "surface": [
+        "cli",
+        "mcp"
+      ],
+      "subforms": {
+        "customer": {
+          "form": "--customer [--json]",
+          "args": [
+            "--customer",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只读自检：**不建目录、不写文件、不碰 settings.yaml/credentials、不真发通知**；可写性用 access(W_OK) 探（**不落探针文件**）。零副作用自证在 JSON 的 sideEffects"
+          },
+          "jsonFields": {
+            "always": [
+              "ok",
+              "empty",
+              "code",
+              "reason"
+            ],
+            "echo": [
+              "verb",
+              "subcommand",
+              "form",
+              "argent",
+              "generatedAt",
+              "dataDir",
+              "licenseState",
+              "interpreterPath",
+              "hostApplicable",
+              "skillRootsScanned",
+              "summary"
+            ],
+            "optional": [
+              "checks",
+              "sideEffects",
+              "authoritative",
+              "error",
+              "usage"
+            ],
+            "emptyCapable": false,
+            "note": "`checks[]` 每条 = {id,title,level(ok|warn|fail),applicable,detail,advice,evidence}"
+          },
+          "a2": {
+            "compliant": true,
+            "note": "全 ok/warn ⇒ 0（warn **只在 JSON 标记**，不占用 2）；存在 fail ⇒ 1 + reason=check_failed；用法错误 ⇒ 2 + usage_error。⛔ **无 dsh 不报 FAIL**（宿主档事实记 applicable:false「本档不适用」= M1 判据③）；缺许可 ⇒ warn + reason=missing（不算 FAIL）"
+          },
+          "in": {
+            "type": "object",
+            "properties": {
+              "customer": {
+                "type": "boolean",
+                "const": true
+              },
+              "json": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "customer"
+            ],
+            "additionalProperties": false
+          },
+          "note": "客户机**一页式自检**（整机、只读、**不要求 dsh**）：数据目录 / 解释器 / 外发技能 / 许可 / 通知通道 / 数据源可达性（只读探测，不读远端表）/ 宿主档事实（applicable:false = 本档不适用）。判据全部来自既有唯一入口（J7 许可 / J9 数据目录 / D3 解释器 / P2 通道端口 / 注册表合并）—— 本 verb **不新增判断**。实现 core/lib/doctor-customer.mjs；跑法 `node core/cli/argent.mjs doctor --customer [--json]`"
+        },
+        "flow": {
+          "form": "--flow <id> [--online] [--json]",
+          "args": [
+            "--flow",
+            "--online",
+            "--json"
+          ],
+          "exitCodes": [
+            0,
+            1,
+            2
+          ],
+          "dryRun": {
+            "supported": false,
+            "default": false,
+            "note": "只读：转发 scripts/flow_preflight.py"
+          },
+          "jsonFields": {
+            "always": [
+              "ok"
+            ],
+            "passthrough": [
+              "output"
+            ],
+            "echo": [
+              "flow",
+              "online"
+            ],
+            "optional": [
+              "code",
+              "error"
+            ],
+            "emptyCapable": false
+          },
+          "a2": {
+            "compliant": false,
+            "pending": "按 D4 用 0 + JSON 标记承载 WARN（被包脚本退出码不在本批改）"
+          },
+          "in": {
+            "type": "object",
+            "properties": {
+              "flow": {
+                "type": "string"
+              },
+              "online": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "flow"
+            ],
+            "additionalProperties": false
+          },
+          "note": "**单流程**前置检查（逐字保留旧行为）：缺 lark-cli 身份/表权限/推送身份/角色 BOT ⇒ 响亮报出 + 人工操作指南"
+        }
+      }
+    },
+    "failures": {
+      "name": "failures",
+      "mcpOnly": true,
+      "args": [],
+      "exitCodes": [],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "MCP 面无退出码"
+      },
+      "jsonFields": {
+        "mcpNote": "MCP 面用 isError + JSON；无进程退出码"
+      },
+      "a2": {
+        "compliant": null,
+        "note": "MCP 专属面：A2 的 code/退出码不适用（P1 后续批次对齐 isError + reason）"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "surface": [
+        "mcp"
+      ]
+    },
+    "shadow_compare": {
+      "name": "shadow_compare",
+      "mcpOnly": true,
+      "args": [],
+      "exitCodes": [],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "MCP 面（影子沙箱本身就是隔离）"
+      },
+      "jsonFields": {
+        "mcpNote": "MCP 面用 isError + JSON"
+      },
+      "a2": {
+        "compliant": null,
+        "note": "MCP 专属面"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          },
+          "fixture": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok",
+          "verified",
+          "ticketsA",
+          "ticketsB",
+          "diffCount"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "verified": {
+            "type": "boolean"
+          },
+          "okReason": {
+            "type": "string"
+          },
+          "ticketsA": {
+            "type": "number"
+          },
+          "ticketsB": {
+            "type": "number"
+          },
+          "diffCount": {
+            "type": "number"
+          },
+          "ticketsEqual": {
+            "type": "boolean"
+          }
+        }
+      },
+      "surface": [
+        "mcp"
+      ]
+    },
+    "writeback_shadow": {
+      "name": "writeback_shadow",
+      "mcpOnly": true,
+      "args": [],
+      "exitCodes": [],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "note": "影子 = 沙箱内的预演（真台账零改动）"
+      },
+      "jsonFields": {
+        "mcpNote": "MCP 面用 isError + JSON"
+      },
+      "a2": {
+        "compliant": null,
+        "note": "MCP 专属面"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "recordId": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "recordId"
+        ],
+        "additionalProperties": false
+      },
+      "surface": [
+        "mcp"
+      ]
+    },
+    "writeback_audit": {
+      "name": "writeback_audit",
+      "mcpOnly": true,
+      "args": [],
+      "exitCodes": [],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读审计查询"
+      },
+      "jsonFields": {
+        "mcpNote": "MCP 面用 isError + JSON"
+      },
+      "a2": {
+        "compliant": null,
+        "note": "MCP 专属面"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "recordId": {
+            "type": "string"
+          },
+          "tail": {
+            "type": "number"
+          }
+        },
+        "additionalProperties": false
+      },
+      "surface": [
+        "mcp"
+      ]
+    },
+    "claim_shadow": {
+      "name": "claim_shadow",
+      "mcpOnly": true,
+      "args": [],
+      "exitCodes": [],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "note": "影子认领（隔离沙箱内真跑 CLI 路径）"
+      },
+      "jsonFields": {
+        "mcpNote": "MCP 面用 isError + JSON"
+      },
+      "a2": {
+        "compliant": null,
+        "note": "MCP 专属面；此前只在 scope 表里出现、没有 verb 块（本轮补齐四处一致）"
+      },
+      "surface": [
+        "mcp"
+      ]
+    },
+    "preflight": {
+      "name": "preflight",
+      "mcpOnly": true,
+      "args": [],
+      "exitCodes": [],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "MCP 面（只读；不写表、不认领）"
+      },
+      "jsonFields": {
+        "mcpNote": "MCP 面用 isError + JSON；无进程退出码"
+      },
+      "a2": {
+        "compliant": null,
+        "note": "MCP 专属面：与 `doctor` 调**同一个脚本**（scripts/flow_preflight.py），判据只有一份"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "flow": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "flow"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "required": [
+          "ok"
+        ],
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "output": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        }
+      },
+      "surface": [
+        "mcp"
+      ],
+      "note": "P1 第二批补：MCP tool `argent_preflight` 此前**没有 verb 块** ⇒ 门禁的“schema ↔ MCP tools”自洽检查会漏（本轮同时补门禁方向 R1g）"
+    },
+    "notify": {
+      "name": "notify",
+      "args": [
+        "--channel",
+        "--url",
+        "--target",
+        "--text",
+        "--file",
+        "--body-json",
+        "--kind",
+        "--summary",
+        "--header",
+        "--idempotency-key",
+        "--timeout-ms",
+        "--apply",
+        "--send",
+        "--confirm",
+        "--yes",
+        "--dry-run",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "note": "写类 verb：**默认即 dry-run**（不投递、不落去重标记、不写审计）；真发要显式确权 --apply/--send/--confirm/--yes。dry-run 与真跑共用同一条判据路径（通道/目标/去重照判）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "channel",
+          "target",
+          "kind",
+          "summary",
+          "bodySource",
+          "bodyBytes",
+          "idempotencyKey",
+          "idempotencyKeySource",
+          "timeoutMs",
+          "dryRun",
+          "sent",
+          "skipped"
+        ],
+        "optional": [
+          "wouldSend",
+          "dedup",
+          "http",
+          "audit",
+          "deliveredAt",
+          "note",
+          "error",
+          "usage",
+          "channels"
+        ],
+        "emptyCapable": true,
+        "reasonWhenEmpty": "duplicate_suppressed"
+      },
+      "a2": {
+        "compliant": true,
+        "note": "P2 落地：端口在 core/lib/notify/（通道实现可替换，feishu/wecom 为预留位 ⇒ 选中报 channel_not_implemented/exit 2）；判据（去重/审计/dry-run）在 verb 层，通道只负责投递"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "channel": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "target": {
+            "type": "string"
+          },
+          "text": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string"
+          },
+          "bodyJson": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "header": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "idempotencyKey": {
+            "type": "string"
+          },
+          "timeoutMs": {
+            "type": "number"
+          },
+          "dryRun": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "channel"
+        ],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sent": {
+            "type": "boolean"
+          },
+          "skipped": {
+            "type": "boolean"
+          },
+          "dedup": {
+            "type": "object"
+          },
+          "http": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "ok",
+          "empty",
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "init": {
+      "name": "init",
+      "args": [
+        "--apply",
+        "--dry-run",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        2
+      ],
+      "dryRun": {
+        "supported": true,
+        "default": true,
+        "note": "写类（只写数据目录本身）：**默认 dry-run**（只画像、不建目录），--apply 才 mkdir -p；dry-run 零副作用"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "dataDir",
+          "dryRun",
+          "applied",
+          "created",
+          "interpreter"
+        ],
+        "optional": [
+          "skills",
+          "license",
+          "channels",
+          "host",
+          "writes",
+          "pendingDecisions",
+          "note",
+          "error"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": true,
+        "note": "P1 第三批：数据目录画像（判断⑧）——数据目录/来源/隔离、解释器候选、已装技能、许可三态、通道可用性、宿主档事实（缺 dsh 不算 FAIL）。⛔ 不写 settings.yaml / credentials"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "apply": {
+            "type": "boolean"
+          },
+          "dryRun": {
+            "type": "boolean"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "dataDir": {
+            "type": "object"
+          },
+          "dryRun": {
+            "type": "boolean"
+          },
+          "applied": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok",
+          "empty",
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "versions": {
+      "name": "versions",
+      "args": [
+        "--only",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb（不发包、不落盘、不建目录）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "only",
+          "dataDir",
+          "cli",
+          "contracts",
+          "kernel",
+          "capabilities",
+          "patches",
+          "host",
+          "interpreter"
+        ],
+        "optional": [
+          "error",
+          "note"
+        ],
+        "emptyCapable": false
+      },
+      "a2": {
+        "compliant": true,
+        "note": "P1 第三批：五面对账（CLI/契约/内核整树 sha/能力包/宿主补丁+宿主版本）；解释器不可用 ⇒ exit 2 + python_unavailable（能力包面**未对账**，不是「无差异」）"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "only": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "kernel": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "capabilities": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "ok",
+          "empty",
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "surface": [
+        "cli"
+      ]
+    },
+    "audit": {
+      "name": "audit",
+      "args": [
+        "--source",
+        "--since",
+        "--tail",
+        "--json"
+      ],
+      "exitCodes": [
+        0,
+        1,
+        2
+      ],
+      "dryRun": {
+        "supported": false,
+        "default": false,
+        "note": "只读 verb（永不写审计；读全量 → 过滤 → 合并排序 → 取末尾 N 行）"
+      },
+      "jsonFields": {
+        "always": [
+          "ok",
+          "empty",
+          "code",
+          "reason"
+        ],
+        "echo": [
+          "sources",
+          "sourceCount",
+          "since",
+          "sinceInput",
+          "tail",
+          "scanned",
+          "matched",
+          "returned",
+          "rowsTruncated",
+          "perSource",
+          "dataDir"
+        ],
+        "optional": [
+          "rows",
+          "error",
+          "note"
+        ],
+        "emptyCapable": true,
+        "reasonWhenEmpty": "no_match"
+      },
+      "a2": {
+        "compliant": true,
+        "note": "P1 第三批：4 处审计 JSONL 只读汇总（invoice-writeback / license-gate / notify-outbox / env-writeback）；先过滤后截断（D1 的教训），空结果回显每源计数"
+      },
+      "in": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "since": {
+            "type": "string"
+          },
+          "tail": {
+            "type": "number"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "out": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "empty": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "number"
+          },
+          "reason": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "rows": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            }
+          },
+          "returned": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "ok",
+          "empty",
+          "code"
+        ],
+        "additionalProperties": false
+      },
+      "surface": [
+        "cli"
+      ]
+    }
+  },
+  "scope": {
+    "$comment": "作用域：local=只在该机器有意义（写台账/回写生产表）；account=账号级只读或门禁写。**必须与 verbs 逐键对齐**（门禁双向查：schema⊆scope 且 scope⊆schema）。",
+    "local": [
+      "flow",
+      "claim",
+      "triage",
+      "writeback",
+      "writeback_shadow",
+      "claim_shadow",
+      "ledger",
+      "source",
+      "gap",
+      "notify",
+      "init",
+      "audit"
+    ],
+    "account": [
+      "version",
+      "sop",
+      "license",
+      "doctor",
+      "report",
+      "failures",
+      "shadow_compare",
+      "writeback_audit",
+      "preflight",
+      "versions"
+    ]
+  },
+  "surfaceNote": "surface 标注每个 verb 的**可用面**：cli=有 `argent <verb>` 实现；mcp=经 MCP 暴露。MCP 专属的（影子比对/回写影子/审计）依赖沙箱与审计机制，暂只在 MCP 面提供 —— 门禁断言三方向：CLI⊆schema、schema.cli⊆CLI、schema⊆MCP tools。（`source`/`gap` 是 CLI 独有面；`failures` 目前只在 MCP 面提供。）（P1 第二批：`license` 为组 verb，子命令清单见 verbs.license.subcommands；`preflight` 是 MCP 专属面 —— 判据与 `doctor` 同脚本。门禁断言四方向：CLI⊆schema、schema.cli⊆CLI、schema⊆MCP tools、契约.verbs.license.subcommands ⊆ schema.verbs.license.subcommands。）"
+}