@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/core/contracts/argent.contracts.json

@@ -0,0 +1,1065 @@
+{
+  "argentVersion": "0.6.0",
+  "principle": "宿主无关：宿主只依赖 `argent <verb>`；确定性逻辑在 CLI/MCP，不在提示词里。",
+  "verbs": {
+    "version": {
+      "kind": "read",
+      "desc": "Argent 版本 + dsh 版本 + 计费模式",
+      "args": []
+    },
+    "sop": {
+      "kind": "read",
+      "desc": "取流程 SOP（提示词/技能目录/踩坑）",
+      "args": [
+        "--flow"
+      ]
+    },
+    "source": {
+      "kind": "read",
+      "desc": "按注册表 source.kind 拉源 → cases",
+      "args": [
+        "--flow",
+        "--json"
+      ]
+    },
+    "flow": {
+      "kind": "group",
+      "desc": "流程族：claim（原子认领，默认 dry-run）｜triage（只出计划，旧 claim 行为）｜list（注册表只读清单）",
+      "args": [
+        "claim",
+        "triage",
+        "list"
+      ],
+      "subcommands": {
+        "claim": "原子认领（planned + 租约）；默认 dry-run，真写要 --apply/--confirm",
+        "triage": "只出计划不落台账（旧 `claim` 行为，逐字保留）",
+        "list": "注册表只读清单（薄包 flow_registry.py --json；不实现合并）"
+      }
+    },
+    "claim": {
+      "kind": "write",
+      "desc": "原子认领待跑票（台账 planned + 租约）；默认 dry-run",
+      "args": [
+        "--flow",
+        "--max",
+        "--lease-min",
+        "--cases-from-dir",
+        "--apply",
+        "--plan-only",
+        "--json"
+      ],
+      "guarantees": [
+        "idempotent",
+        "audited",
+        "dry-run-by-default"
+      ],
+      "legacyPlanOnly": "`claim --plan-only` = 旧的分诊行为（等价 `flow triage`）；改名只为把名字还给真正的认领"
+    },
+    "triage": {
+      "kind": "read",
+      "desc": "分诊计划（只出计划，不落台账）—— 旧 `claim` 行为，逐字保留",
+      "args": [
+        "--flow",
+        "--cases-from-dir",
+        "--json"
+      ]
+    },
+    "gap": {
+      "kind": "read",
+      "desc": "字段缺口检查",
+      "args": [
+        "--flow",
+        "--ticket"
+      ]
+    },
+    "writeback": {
+      "kind": "write",
+      "desc": "白名单守卫回写（写前备份/写后读回/审计）",
+      "args": [
+        "--flow",
+        "--record-id",
+        "--allow-record"
+      ],
+      "guarantees": [
+        "whitelist",
+        "backup",
+        "readback",
+        "audit"
+      ]
+    },
+    "report": {
+      "kind": "net",
+      "desc": "失败上报（带 DOM/日志证据）",
+      "args": [
+        "--flow",
+        "--ticket",
+        "--step"
+      ]
+    },
+    "ledger": {
+      "kind": "read",
+      "desc": "台账查询（唯一真相）",
+      "args": [
+        "--flow",
+        "--tail"
+      ]
+    },
+    "license": {
+      "kind": "read",
+      "desc": "离线许可组：status（三态+能力门+设备）｜verify（验签本身）｜install --file（默认 dry-run）｜request（设备码）｜renew --file（默认 dry-run）｜explain（缺什么/下一步）｜activate --code（一次性激活码兑换：默认 dry-run，真兑换要 --apply）｜ops（只读运营巡检 O2：在途码/失败码/事件时间线/席位账目/异常清单，替代 mongosh）",
+      "args": [
+        "status",
+        "verify",
+        "install",
+        "request",
+        "renew",
+        "explain",
+        "activate",
+        "ops"
+      ],
+      "subcommands": {
+        "status": "三态（valid/grace/denied）+ 能力/业务线命中 + 设备绑定态；透传 check-license 退出码 0/3/1/2",
+        "verify": "只验一份许可（HMAC-SHA256 + canonicalJson + 判期 + 设备比对），**不落盘**",
+        "install": "验签 + 设备比对后落盘（0600 / 临时文件 rename / 覆盖前备份）；**默认 dry-run**，真写要 --apply",
+        "request": "打印**设备码**（离线激活第一步；指纹只认 IOPlatformUUID，禁止主机名/MAC/IP/安装路径）",
+        "renew": "续期：离线 = 换一份新许可文件（默认 dry-run）；没有新文件 ⇒ 成功但空（empty:true），**绝不当 denied**",
+        "explain": "把三态翻译成「缺什么 / 下一步做什么」（只重组 check-license --json 的既有字段）",
+        "activate": "一次性激活码兑换（方案 §9）：用网页/手机端**登录后**生成的一次性码，换一份**绑定本机设备码**的许可。**默认 dry-run**（零网络请求 + 零落盘，连审计都不落），真兑换要 `--apply`。两步：先 `argent license request` 拿设备码 → 再 `activate --code <码>`。落盘复用 `scripts/install-license.mjs` 的既有判据（验签/设备比对/0600/备份/读回/幂等/拒绝倒退）；**明文码绝不出现在任何输出里**（只回显 codePrefix）。",
+        "ops": "只读运营巡检（O2：替代 `mongosh`）：在途码（state∈issued|redeeming + TTL 剩余/failCount）｜失败码（failCount>0 或 revoked + code_redeem_denied/code_revoke_denied 计数）｜近 N 天事件时间线（只 action/result/codePrefix）｜席位账目（seats + deviceLimit（缺省跟随 seats）+ used=releasedAt 为空的设备码去重数）｜异常清单（在途码超 TTL 未终态 / 同设备挂多账号且均未释放 / audit 里 device_release/rejected 探针痕迹 / …）。**只读且零副作用**：不写任何集合/文件/审计，HTTP 只发 GET（⛔ 绝不调 POST /release-device）。数据源三选一：`--from <快照>`｜`--server <base>`（管理员 JWT，只从 600 的 `*.env` 读）｜缺省=本机只读产物。答不了的节**如实标 available:false + needs**，⛔ 不用 0 充数；两个已知陷阱（`state` 不是 `status`、席位是算出来的）一律 `field_missing`（exit 2）响亮失败。"
+      }
+    },
+    "doctor": {
+      "kind": "read",
+      "desc": "环境自检：`--customer` = 客户机一页式自检（整机/只读/**不要求 dsh**）；`--flow <id>` = 单流程前置检查（转发 flow_preflight.py）",
+      "args": [
+        "--customer",
+        "--flow",
+        "--online",
+        "--json"
+      ],
+      "subforms": {
+        "customer": {
+          "form": "--customer [--json]",
+          "exitCodes": [
+            0,
+            1,
+            2
+          ],
+          "desc": "客户机一页式自检（M1 判据③）：数据目录 / 解释器 / 外发技能 / 许可 / 通知通道 / 数据源可达性 / 宿主档事实",
+          "sevenChecks": [
+            "data_dir",
+            "interpreter",
+            "skills",
+            "license",
+            "channels",
+            "source",
+            "host"
+          ],
+          "levels": {
+            "ok": "通过",
+            "warn": "需看一眼（**不改变退出码**）",
+            "fail": "硬失败（exit 1 + reason=check_failed）"
+          },
+          "notFail": [
+            "无 dsh（宿主档事实记 applicable:false「本档不适用」）",
+            "缺许可（reason=missing ⇒ warn）",
+            "缺技能/只装一半（warn + 安装命令）",
+            "数据目录不存在但可建（warn + init --apply）"
+          ],
+          "judgmentsFrom": [
+            "J7-license-three-state",
+            "J9-data-dir-audit-backup",
+            "core/lib/python.mjs（D3）",
+            "core/lib/notify/index.mjs（P2 端口）",
+            "scripts/flow_registry.py（注册表唯一真源）"
+          ],
+          "noNewJudgment": "本子形态**不新增判断**：每条检查都调既有唯一入口，只把事实分成 ok/warn/fail 三档并给处置建议",
+          "sideEffects": {
+            "writes": "none",
+            "settings": false,
+            "credentials": false,
+            "notifications": false,
+            "note": "JSON 的 sideEffects 是机器可读自证；回归用「夹具目录逐文件 sha 前后一致」验（scripts/tests/doctor-customer.test.mjs）"
+          },
+          "impl": "core/lib/doctor-customer.mjs"
+        },
+        "flow": {
+          "form": "--flow <id> [--online] [--json]",
+          "desc": "单流程前置检查（逐字保留旧行为，转发 scripts/flow_preflight.py；缺 --flow ⇒ 2）",
+          "impl": "scripts/flow_preflight.py"
+        }
+      }
+    },
+    "notify": {
+      "kind": "net",
+      "desc": "通知投递（P2）：通道选择 + 幂等去重 + dry-run；默认 dry-run，真发要 --apply",
+      "args": [
+        "--channel",
+        "--url",
+        "--target",
+        "--text",
+        "--file",
+        "--body-json",
+        "--kind",
+        "--summary",
+        "--header",
+        "--idempotency-key",
+        "--timeout-ms",
+        "--apply",
+        "--send",
+        "--dry-run",
+        "--json"
+      ]
+    },
+    "init": {
+      "kind": "read",
+      "desc": "数据目录画像（判断⑧）：数据目录/解释器候选/已装技能/许可/通道/宿主档事实；默认 dry-run，--apply 才建目录",
+      "args": [
+        "--apply",
+        "--dry-run",
+        "--json"
+      ]
+    },
+    "versions": {
+      "kind": "read",
+      "desc": "版本对账（只读）：CLI/契约/内核整树 sha/能力包版本/宿主补丁清单/宿主版本",
+      "args": [
+        "--only",
+        "--json"
+      ]
+    },
+    "audit": {
+      "kind": "read",
+      "desc": "审计 JSONL 只读汇总：先全量→按 --since 过滤→合并排序→取末尾 N 行",
+      "args": [
+        "--source",
+        "--since",
+        "--tail",
+        "--json"
+      ]
+    }
+  },
+  "judgmentMeta": {
+    "purpose": "判断面清单（P0 0.1）：把「哪些判断必须由 L1 做」从默契变成清单 + 可判形式。宿主只做「选 verb → 读 $? 与 JSON → 按 reason 处置」，不得复述本段任何常量。",
+    "ownerForm": "<仓库相对路径>:<行号>（1-based）。owner = 主实现位置；implementations = 全部已声明实现位置（含 owner，逐条带 anchor）。",
+    "ownerSlackLines": 25,
+    "anchorRule": "anchor 是逐字字面量，必须出现在该实现文件的 [行号−slack, 行号+slack] 内；同一 anchor 出现在扫描面里的**未声明**文件 ⇒ 报漂移（代码有契约没有）。",
+    "scan": {
+      "globs": [
+        "core/**/*.mjs",
+        "core/**/*.js",
+        "scripts/**/*.mjs",
+        "scripts/**/*.py"
+      ],
+      "excludeGlobs": [
+        "scripts/tests/**",
+        "scripts/archive/**",
+        "scripts/patches/**"
+      ],
+      "note": "扫描面 = L1 代码文件（契约 §1：core/ + scripts/ 引擎）；测试/归档/补丁不算实现位。glob 与 anchor 全部来自本文件，门禁不另写第二份清单。"
+    },
+    "restateRule": "复述判据（P0 0.4 / §P0-A V1）：skills/**/SKILL.md、verticals/**/prompts/*.md 与 presets/**/*.yml（2026-10-04 扩展，A5）里，同一行命中 ≥2 个 restateTokens 且**无引用点**（judgmentMeta.restateCitationTokens）⇒ 记一条告警（默认只 warn，--strict 才红）。token 同样从本清单读。",
+    "restateScan": {
+      "globs": [
+        "skills/**/SKILL.md",
+        "verticals/**/prompts/*.md",
+        "presets/**/*.yml"
+      ],
+      "excludeGlobs": [],
+      "citationTokens": [
+        "argent ",
+        "scripts/flow_",
+        "flows.json",
+        "flow-requirements.json",
+        "core/contracts/"
+      ],
+      "baselineNote": "首日允许非零（§2.3 D5 基线：白名单枚举 4 处、终态枚举 6 处）；先 warn + 基线清单、后收紧，否则就是恒红陷阱。｜**2026-10-04 扩展扫描面到 `presets/**/*.yml`**（角色 preset 的 persona 也是提示词，此前不在扫描面 ⇒ 盘点文档 §4-③ 的 2 处 J2 白名单复述「门禁看不见」）：扩展后**首测 +2**（`presets/argent-ml-invoice-{wy,xzh}/agent.cordis.yml` 的同一行逐字枚举四字段）——同批已改成**引用**（写手姿态 `argent writeback --print-posture` 的 `allowedFields`，声明在 `flow-requirements.json#capabilities.invoice.writeFields`）⇒ **presets 命中 0**；同一处「在飞上限 2」也改成不写数字（该常量 CLI/契约里根本没有）。**扩展后基线 = skills/ 20 条不变（终态/状态机/历史证据类，下一批收口），presets/ 0 条**；口径仍是先 warn（`--strict` 才红），不一次全红。",
+      "minTokens": 2
+    },
+    "exitCodes": "见 core/contracts/verbs.schema.json#exitCodes（唯一口径，A1）；本文件的每条 onReject.code 必须落在该表内。",
+    "onRejectForm": "{ code, reason, effect }：code 见 verbs.schema.json#exitCodes；reason 见本文件 reasonCodes；effect = 处置（谁该做什么）。",
+    "reasonScanGlobs": [
+      "core/lib/claim.mjs",
+      "core/lib/ledger.mjs",
+      "core/lib/license.mjs",
+      "core/lib/license-device.mjs",
+      "core/lib/license-verdict.mjs",
+      "core/lib/license-guard.mjs",
+      "core/lib/notify/verb.mjs",
+      "core/lib/notify/index.mjs",
+      "core/lib/notify/webhook.mjs",
+      "core/lib/notify/feishu.mjs",
+      "core/lib/notify/wecom.mjs",
+      "core/lib/doctor-customer.mjs",
+      "core/lib/license-activate.mjs",
+      "core/lib/license-ops.mjs"
+    ],
+    "reasonScanNote": "A2 适配层里发出的 reason 短码必须在 reasonCodes 里（P1 第二批起覆盖 `core/lib/license*.mjs`；P1 第三批起覆盖 P2 通知端口 `core/lib/notify/*.mjs`）。P4 起覆盖客户机自检 `core/lib/doctor-customer.mjs`（fail 短码 = check_failed）。其余 verb 的 a2.compliant=false 已如实登记，待后续批次收口。一次性激活码兑换（`core/lib/license-activate.mjs`）同批纳入扫描面：它发出的每个短码都必须在 reasonCodes 里。 只读运营巡检（`core/lib/license-ops.mjs`，O2）同批纳入扫描面：它发出的每个短码都必须在 reasonCodes 里（`field_missing` 为它新增 —— 两个已知陷阱的响亮失败码）。"
+  },
+  "judgments": {
+    "J1-source-pick-gate": {
+      "id": "J1",
+      "title": "数据源门禁与必需字段（候选收窄 · 缺口归桶）",
+      "owner": "scripts/flow_sources/common.py:264",
+      "implementations": [
+        {
+          "at": "scripts/flow_sources/common.py:264",
+          "anchor": "def apply_pick"
+        },
+        {
+          "at": "scripts/flow_sources/common.py:407",
+          "anchor": "def required_projection"
+        },
+        {
+          "at": "scripts/flow_sources/common.py:231",
+          "anchor": "def wanted_pick_columns"
+        }
+      ],
+      "declaredIn": [
+        "verticals/*/flows.json#flows.*.source.pick",
+        "verticals/*/flows.json#flows.*.required"
+      ],
+      "inputs": [
+        "源行 fields",
+        "流程声明的 source.pick（equals / excludeEquals / excludeAllPresent）",
+        "流程声明的 required[].role（input/state 才拉，output/derived 不拉）"
+      ],
+      "outputs": [
+        "候选行集合（收窄后）",
+        "必需字段投影列名",
+        "缺口按 owner 归桶：need_fields（运营补数据，落卡等人）/ 仍可派发（系统字段）"
+      ],
+      "onReject": {
+        "code": 0,
+        "reason": "no_ticket",
+        "effect": "收窄后为空是**合法结论**（本轮无事可做），不是错误；必须带 notes 说明为何为空（已推送/未到点/窗口已过/等人补字段）"
+      }
+    },
+    "J2-writeback-whitelist": {
+      "id": "J2",
+      "title": "回写白名单（字段级 + 记录级 + 单向释放字段）",
+      "owner": "scripts/wenyao-invoice-writeback.mjs:79",
+      "implementations": [
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:79",
+          "anchor": "export const ALLOWED_FIELDS"
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:93",
+          "anchor": "export const ONEWAY_FALSE_FIELDS"
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:152",
+          "anchor": "export function guardRecord"
+        }
+      ],
+      "declaredIn": [
+        "scripts/flow-requirements.json#capabilities.invoice.writeFields"
+      ],
+      "inputs": [
+        "目标字段名 + 值",
+        "--allow-record <recordId>（记录白名单必填）",
+        "附件字段标记（附件只能走上传通道，不能当普通值写）"
+      ],
+      "outputs": [
+        "guardPatch 结论：{ok:true} 或 {ok:false, error}",
+        "被拒原因串（field-not-whitelisted / attachment-field-needs-upload / missing-allow-record / record-not-whitelisted）"
+      ],
+      "onReject": {
+        "code": 1,
+        "reason": "guard_rejected",
+        "effect": "拒绝且**零副作用**（不许先写后撤回）；调用方按 error 串改参数或请人，不得当成功继续"
+      },
+      "restateTokens": [
+        "发票状态",
+        "发票文件",
+        "大货标签",
+        "发票错误信息"
+      ]
+    },
+    "J3-terminal-state": {
+      "id": "J3",
+      "title": "状态机与终态（终态需 --force；同一个值 = noop）",
+      "owner": "scripts/wenyao-invoice-writeback.mjs:160",
+      "implementations": [
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:160",
+          "anchor": "export function guardStatusTransition"
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:94",
+          "anchor": "export const STATUS_OPTIONS"
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:100",
+          "anchor": "export const STATUS_TERMINAL"
+        }
+      ],
+      "declaredIn": [
+        "verticals/*/flows.json#flows.*.guards"
+      ],
+      "inputs": [
+        "当前状态（规范化后）",
+        "目标状态",
+        "--force（显式确权）"
+      ],
+      "outputs": [
+        "{ok:true, action:'write'|'noop', from, to} 或 {ok:false, error}",
+        "终态判定：from ∈ STATUS_TERMINAL ⇒ 无 --force 即拒"
+      ],
+      "onReject": {
+        "code": 1,
+        "reason": "guard_rejected",
+        "effect": "拒绝写（terminal-status-needs-force / unknown-status）；重跑终态行必须由人显式加 --force"
+      },
+      "restateTokens": [
+        "已上传",
+        "标签已下载",
+        "已完成"
+      ]
+    },
+    "J4-failure-classification": {
+      "id": "J4",
+      "title": "失败分类阈值（retryable / needs_human / needs_agent）",
+      "owner": "scripts/flow_failure.py:118",
+      "implementations": [
+        {
+          "at": "scripts/flow_failure.py:118",
+          "anchor": "GROUPS = (('capacityFull', 'needs_human')"
+        },
+        {
+          "at": "scripts/flow_failure.py:121",
+          "anchor": "DEFAULT_KIND ="
+        }
+      ],
+      "declaredIn": [
+        "scripts/flow-requirements.json#failureClasses"
+      ],
+      "inputs": [
+        "错误文本（stdout/stderr/DOM 证据）",
+        "尝试次数 attempt"
+      ],
+      "outputs": [
+        "kind ∈ {retryable, needs_human, needs_agent}（未知一律 needs_agent）",
+        "命中的**组**名（capacityFull / pageFlaky / …）进 reason，便于区分是哪条链",
+        "是否唤醒掌舵者：只有 needs_agent 叫醒"
+      ],
+      "onReject": {
+        "code": 0,
+        "reason": "no_ticket",
+        "effect": "分类本身不失败；阈值改变 = 契约级改动（规则唯一权威是 flow-requirements.json#failureClasses，禁止在 SKILL/提示词里另写一套）"
+      },
+      "restateTokens": [
+        "retryable",
+        "needs_human",
+        "needs_agent"
+      ]
+    },
+    "J5-idempotency-key": {
+      "id": "J5",
+      "title": "幂等键（caseId = flowId__ticketKey；台账是唯一真相）",
+      "owner": "scripts/flow_sources/common.py:387",
+      "implementations": [
+        {
+          "at": "scripts/flow_sources/common.py:387",
+          "anchor": "def ticket_key"
+        },
+        {
+          "at": "scripts/flow_case.py:66",
+          "anchor": "def case_id"
+        }
+      ],
+      "declaredIn": [
+        "verticals/*/flows.json#flows.*.source.ticketKey",
+        "core/lib/ledger.mjs#queryLedger"
+      ],
+      "inputs": [
+        "源行 record_id",
+        "票号列的值",
+        "流程声明的 source.ticketKey（record_id | ticketField，缺省=票号列优先）"
+      ],
+      "outputs": [
+        "ticketKey（行身份）",
+        "caseId（幂等键：同流程同票 = 同 case ⇒ 不重复建案/不重复派发）"
+      ],
+      "onReject": {
+        "code": 0,
+        "reason": "no_ticket",
+        "effect": "身份取不到 ⇒ 该行不进候选（不是错误）；⛔ 不许用「目录里最新的文件」之类的兜底冒充身份"
+      }
+    },
+    "J6-lease-and-concurrency": {
+      "id": "J6",
+      "title": "租约与并发（planned + leaseUntil；按店/按 IP 限并发）",
+      "owner": "scripts/flow_claim.py:92",
+      "implementations": [
+        {
+          "at": "scripts/flow_claim.py:92",
+          "anchor": "def live_leases"
+        },
+        {
+          "at": "scripts/flow_claim.py:128",
+          "anchor": "def select_candidates"
+        },
+        {
+          "at": "scripts/flow_claim.py:180",
+          "anchor": "def planned_record"
+        }
+      ],
+      "declaredIn": [
+        "verticals/*/flows.json#flows.*.concurrency",
+        "scripts/flow-requirements.json#lease"
+      ],
+      "inputs": [
+        "台账里的最新事件（planned / done / failed / blocked）",
+        "leaseUntil 与 now",
+        "流程配置 concurrency（max / leaseMin / perStore / batchPerStore / perIp）"
+      ],
+      "outputs": [
+        "本轮可认领的票（atomic：锁内 读 triage → 选票 → 写 planned）",
+        "每店/每 IP 的在飞计数"
+      ],
+      "onReject": {
+        "code": 0,
+        "reason": "no_ticket",
+        "effect": "无票可认领 = 正常态（exit 0 + empty:true；脚本内部的 3 由 verb 适配层翻译，禁止把 3 用作第二语义）"
+      }
+    },
+    "J7-license-three-state": {
+      "id": "J7",
+      "title": "许可三态与能力门（0 允许 / 3 宽限放行 / 1 拒绝）+ 离线设备绑定（unbound 放行 / mismatch 宽限或拒绝）",
+      "owner": "scripts/check-license.mjs:88",
+      "implementations": [
+        {
+          "at": "scripts/check-license.mjs:88",
+          "anchor": "const exitCode = allowed"
+        },
+        {
+          "at": "scripts/license-gate.mjs:55",
+          "anchor": "export function normalizeMode"
+        },
+        {
+          "at": "core/lib/license-verdict.mjs:49",
+          "anchor": "export function licenseVerdict"
+        },
+        {
+          "at": "core/lib/license-device.mjs:168",
+          "anchor": "export function bindingOf"
+        },
+        {
+          "at": "core/lib/license-device.mjs:46",
+          "anchor": "export function readFingerprint"
+        },
+        {
+          "at": "core/lib/license-guard.mjs:48",
+          "anchor": "export function gateWrite"
+        },
+        {
+          "at": "core/lib/license.mjs:472",
+          "anchor": "export function runLicenseVerb"
+        }
+      ],
+      "declaredIn": [
+        "scripts/flow-requirements.json#lease",
+        "core/lib/license-file.mjs",
+        "core/lib/license-verdict.mjs",
+        "core/lib/license-device.mjs",
+        "core/contracts/verbs.schema.json#verbs.*.licenseGate"
+      ],
+      "inputs": [
+        "许可文件（离线验签 + 有效期 + capabilities）",
+        "--cap / --vertical（能力门）",
+        "闸门模式（off / observe / enforce；默认 observe）",
+        "载荷里**可选**的 `device` 声明 + 本机设备码（指纹**只认 IOPlatformUUID**，D3）",
+        "自助重绑计数（$ARGENT_DATA_DIR/license-rebind.json：3 次 + 7 天宽限）"
+      ],
+      "outputs": [
+        "state ∈ {valid, grace, denied}（**不新增第四态**：设备不匹配在宽限内复用 grace）",
+        "退出码 0 / 3 / 1（3 = 宽限放行，必须上报）",
+        "设备绑定态：unbound / match / rebound / mismatch / unsupported（± reason：unbound、device_mismatch、rebind_exhausted…）",
+        "证据 JSONL（observe 模式只留痕不停派）；写类 verb 在 enforce 下拒绝时**零副作用**"
+      ],
+      "onReject": {
+        "code": 1,
+        "reason": "guard_rejected",
+        "effect": "denied ⇒ 停派/拒写（不带 3）；grace ⇒ 继续跑业务但必须上报。⛔ `device` **未进签名**（v1 只签 9 项）⇒ 只能当“服务端声明 + 客户端比对”，不得当已验签字段引用"
+      }
+    },
+    "J8-readiness-gate": {
+      "id": "J8",
+      "title": "就绪判据（店铺逐字归属 + 运营放行位；Bridge 就绪属宿主档事实）",
+      "owner": "scripts/flow_claim.py:26",
+      "implementations": [
+        {
+          "at": "scripts/flow_claim.py:26",
+          "anchor": "def _ziniao_stores"
+        },
+        {
+          "at": "scripts/flow_claim.py:50",
+          "anchor": "def _ziniao_store_ips"
+        },
+        {
+          "at": "scripts/flow_triage.py:387",
+          "anchor": "def release_gate"
+        }
+      ],
+      "declaredIn": [
+        "verticals/*/flows.json#flows.*.source.fields.store",
+        "verticals/*/flows.json#flows.*.pick.releaseReDispatch"
+      ],
+      "inputs": [
+        "票上的店铺名（逐字，不归一化）",
+        "紫鸟店铺清单（ziniao-cli store list，带 TTL 缓存；取不到 ⇒ 跳过校验，宁可不拦）",
+        "运营勾的放行位（就绪=true）"
+      ],
+      "outputs": [
+        "店铺不在清单 ⇒ 拒该票 + 写 blocked（不猜账号，绝不回退默认账号）",
+        "放行位为真且上游 failed/blocked ⇒ 允许重新派发（受每票上限 + 冷却约束）"
+      ],
+      "onReject": {
+        "code": 0,
+        "reason": "no_ticket",
+        "effect": "被拒的票不进本轮候选（不是失败）；Bridge/客户端就绪属宿主档事实，只在壳体探测并如实上报（契约 §3 矩阵），不得为它改内核"
+      }
+    },
+    "J9-data-dir-audit-backup": {
+      "id": "J9",
+      "title": "数据目录唯一判据 + 审计/备份落点",
+      "owner": "core/lib/argent-datadir.mjs:128",
+      "implementations": [
+        {
+          "at": "core/lib/argent-datadir.mjs:128",
+          "anchor": "export function resolveDataDir"
+        },
+        {
+          "at": "scripts/lib/argent_datadir.py:156",
+          "anchor": "def resolve_data_dir"
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:201",
+          "anchor": "const AUDIT = join("
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:251",
+          "anchor": "function backup(recordId, fieldIds, tag)"
+        }
+      ],
+      "declaredIn": [
+        "core/lib/argent-datadir.mjs",
+        "scripts/lib/argent_datadir.py"
+      ],
+      "inputs": [
+        "环境变量 ARGENT_DATA_DIR / DSH_HOME / HOME"
+      ],
+      "outputs": [
+        "数据目录 dir（三级链：ARGENT_DATA_DIR → $DSH_HOME/argent → ~/.dsh/argent）",
+        "isolated 判据（dir ≠ 默认目录 ⇒ 失败回路安全阀生效）",
+        "写前整行备份（backup/<tag>-<recordId>-<ts>.json）+ 审计 JSONL（audit.jsonl）"
+      ],
+      "onReject": {
+        "code": 1,
+        "reason": "internal_error",
+        "effect": "拿不到数据目录 / 备份写不下 ⇒ 拒绝真写（fail-closed）；⛔ 禁止在别处复制这条链"
+      }
+    },
+    "J10-sideeffect-boundary": {
+      "id": "J10",
+      "title": "副作用边界：--dry-run 零副作用清单 + 通知去重（同一事实不重发）",
+      "owner": "scripts/flow_claim.py:302",
+      "implementations": [
+        {
+          "at": "scripts/flow_claim.py:302",
+          "anchor": "ap.add_argument('--dry-run'"
+        },
+        {
+          "at": "scripts/wenyao-invoice-writeback.mjs:452",
+          "anchor": "if (o['dry-run'])"
+        },
+        {
+          "at": "scripts/daily-report.mjs:691",
+          "anchor": "const markerFile = "
+        },
+        {
+          "at": "core/lib/notify/verb.mjs:149",
+          "anchor": "const dryRun = bools.has('--dry-run')"
+        },
+        {
+          "at": "core/lib/notify/dedup.mjs:57",
+          "anchor": "export function dedupMarkerPath"
+        }
+      ],
+      "declaredIn": [
+        "core/contracts/verbs.schema.json#dryRunContract",
+        "scripts/flow-requirements.json#capabilities.invoice.gate"
+      ],
+      "inputs": [
+        "调用方是否给了确权参数（--apply / --confirm / --yes）",
+        "同一事实的幂等键（.pushed-<date>-<storeKey> 标记）"
+      ],
+      "outputs": [
+        "dry-run：只打印「将要做什么」（目标记录/字段/命令）+ dryRun:true",
+        "真写：落台账/备份/审计，并打幂等标记；重复通知 ⇒ skipped:true"
+      ],
+      "dryRunZeroSideEffectsRef": "core/contracts/verbs.schema.json#dryRunContract.zeroSideEffects",
+      "dryRunZeroSideEffectsNote": "零副作用清单**只有一份**（引用的那份）；本条目不复制它 —— 复述即第二份判据。判据 = 跑两次 dry-run 后数据目录逐字节不变。",
+      "onReject": {
+        "code": 1,
+        "reason": "internal_error",
+        "effect": "dry-run 落了任何一条 ⇒ 违规（判据 = 跑两次 dry-run 后数据目录逐字节不变）；调用方说了算（能靠参数绕过判据）= 红"
+      }
+    }
+  },
+  "reasonCodes": {
+    "_doc": "机器可判的短码（A2）：ok:false 与 empty:true 时必须给；禁止拿中文句子当判据（人话放 error/note）。exit = 该 reason 对应的进程退出码（必须与 verbs.schema.json#exitCodes 一致）。",
+    "no_ticket": {
+      "exit": 0,
+      "meaning": "成功但无事可做（无票可认领 / 收窄后为空）"
+    },
+    "no_match": {
+      "exit": 0,
+      "meaning": "查询类 verb 成功但无匹配行（含被过滤/被截断，须回显生效条件）"
+    },
+    "license_grace": {
+      "exit": 3,
+      "meaning": "许可宽限期内：业务放行，但必须上报"
+    },
+    "guard_rejected": {
+      "exit": 1,
+      "meaning": "写守卫/许可拒绝（白名单、终态、记录授权、超宽限）"
+    },
+    "source_failed": {
+      "exit": 1,
+      "meaning": "数据源读取失败/超时（网络、飞书半开连接）"
+    },
+    "internal_error": {
+      "exit": 1,
+      "meaning": "内部错误（不含用法问题）"
+    },
+    "check_failed": {
+      "exit": 1,
+      "meaning": "`argent doctor --customer` 自检发现 fail 项（数据目录不可写 / 解释器全不可用 / 技能与仓库漂移 / 许可被拒 / 数据面未实现 / 无可用通知通道）",
+      "note": "warn **不**产生该码，也不改变退出码（A1：2 不得再被用作「有告警」）；fail 项在 JSON 的 checks[].id/level 里点名"
+    },
+    "bad_output": {
+      "exit": 1,
+      "meaning": "被包脚本输出不可解析（不是 JSON）"
+    },
+    "missing_declaration": {
+      "exit": 2,
+      "meaning": "注册表里没有这条流程/这个能力（缺声明）"
+    },
+    "usage_error": {
+      "exit": 2,
+      "meaning": "参数/环境错误（缺必填参数、配置引用的 env 缺失）"
+    },
+    "field_missing": {
+      "exit": 2,
+      "meaning": "数据源缺**域必需字段**（或查询用了本域不存在的字段）—— 必须响亮失败，⛔ **不得**降级成\"0 条\"/\"空结果\"",
+      "note": "判据落点 `core/lib/license-ops.mjs#checkOpsFields`/`parseOpsArgs`（O2 的两个已知陷阱）：① 码状态字段是 `state` **不是** `status`（按 `status` 查恒空 ⇒ 会把\"有在途码\"误读成\"没有\"）；② 席位**不是**存储字段 `used`（= `seats` + `deviceLimit`（缺省跟随 seats）+ `releasedAt` 为空的设备码去重数）。⇒ 用错字段名一律 exit 2 + 本码 + `missingFields` 回显，绝不静默返回 0。"
+    },
+    "endpoint_missing": {
+      "exit": 0,
+      "meaning": "**节级**短码（唯一真源 = `core/lib/license-ops.mjs#OPS_SECTION_REASONS`）：服务端**没有**这个只读接口（静态登记 `exists:false`，或**本轮实测 404 路由不在** = 接口已就绪但**还没部署**）⇒ 那一节 `available:false` + `needs`，⛔ **绝不当成「0 条」**；顶层仍 exit 0（「答不了」≠「读失败」）",
+      "note": "宿主在 `json.<section>.reason` 上分支。本轮（2026-10-04）的实测形态：4 个只读接口已在 `whyshu-svr` 就绪但**未部署** ⇒ `argent license ops --server <base>` 会把它标成本码 + `missingEndpoints[].runtime:true`，`--probe` 同时报 `missing` 且 `agrees:false`。"
+    },
+    "needs_server": {
+      "exit": 0,
+      "meaning": "**节级**短码：本机只读产物答不了这一节，要服务端只读接口（`--server <base>`）—— 不是\"没有\"",
+      "note": "唯一真源 = `core/lib/license-ops.mjs#OPS_SECTION_REASONS`。"
+    },
+    "no_prefix": {
+      "exit": 0,
+      "meaning": "**节级**短码：没有可查的码前缀（既没 `--prefix`，本机审计里也没有）—— ⛔ 不是\"没有在途码\"",
+      "note": "唯一真源 = `core/lib/license-ops.mjs#OPS_SECTION_REASONS`。"
+    },
+    "no_data": {
+      "exit": 0,
+      "meaning": "**节级**短码：快照里**没有这个集合**（缺席 ≠ 为空）—— ⛔ 不报 0",
+      "note": "唯一真源 = `core/lib/license-ops.mjs#OPS_SECTION_REASONS`。"
+    },
+    "field_unknown": {
+      "exit": 2,
+      "meaning": "服务端**不认识**这个参数名（典型 = `?status=`；服务端对未知参数一律 400 `field_unknown` 并点名「请用 `state`」）—— 必须响亮失败，⛔ **不得**降级成\"筛出 0 条\"/空集",
+      "note": "判据落点 `core/lib/license-ops.mjs#opsServerGet`（O2 只读运营视图接服务端 4 个只读接口）。服务端契约 §0：`?status=` ⇒ **400 `field_unknown`** + 文案点名\"字段是 `state`\"；客户端把 400/200 上挂的 `ok:false` **按 reason 判定**（⛔ 不看状态码），并原样带上服务端原文与陷阱提示。"
+    },
+    "rate_limited": {
+      "exit": 1,
+      "meaning": "兑换：触发限流 ⇒ 退避重试（**同一个码**重试是安全的：同码同机走幂等复用）"
+    },
+    "method_not_allowed": {
+      "exit": 2,
+      "meaning": "只读接口**只接受 GET**（服务端契约 §0：其它动词 ⇒ 405 + `Allow: GET`）—— 客户端只发 GET，见到 405 即链路/网关不对，⛔ 不是\"没有数据\"",
+      "note": "判据落点 `core/lib/license-ops.mjs#opsServerGet`。同族的 `admin_required`（401/403，`adminAuth` 口径）与 `bad_request`（400 `bad_limit`/`bad_state`/`bad_since`/`bad_device`）也在同一处判定。"
+    },
+    "admin_required": {
+      "exit": 2,
+      "meaning": "只读接口要求**管理员**身份（服务端 `adminAuth`：无令牌 401、非管理员 403）—— 换管理员 JWT，⛔ 不绕过鉴权、⛔ 不降级成空集",
+      "note": "判据落点 `core/lib/license-ops.mjs#opsServerGet`（401/403 同口径）。"
+    },
+    "bad_request": {
+      "exit": 1,
+      "meaning": "兑换：服务端认为请求不合法（字段缺失/类型错）⇒ 客户端与服务端**契约版本不一致**，先核对版本（不反复重试）"
+    },
+    "python_unavailable": {
+      "exit": 2,
+      "meaning": "解释器不可用（多候选全部探测失败）"
+    },
+    "no_ledger": {
+      "exit": 1,
+      "meaning": "台账文件不存在（数据目录不对 / 这台机器从未跑过流程）—— **不得**降级成 empty"
+    },
+    "ok": {
+      "exit": 0,
+      "meaning": "判定通过（许可/设备正常态）—— 只在需要显式回执的 verb 里出现；ok:true 且无事可报时宁可写 null"
+    },
+    "unbound": {
+      "exit": 0,
+      "meaning": "许可未声明设备（无 device 字段）⇒ **不做比对、放行**（存量许可继续有效，D1-兼容）"
+    },
+    "device_match": {
+      "exit": 0,
+      "meaning": "许可声明的设备码与本机一致 ⇒ 放行"
+    },
+    "device_rebound": {
+      "exit": 0,
+      "meaning": "本机自助重绑过这份许可的设备码 ⇒ 放行（计数见 $ARGENT_DATA_DIR/license-rebind.json）"
+    },
+    "device_unsupported": {
+      "exit": 2,
+      "meaning": "本机不支持设备绑定（非 Darwin / 读不到 IOPlatformUUID）⇒ **不 fail-closed**：按 unbound 放行并如实标注"
+    },
+    "device_read_failed": {
+      "exit": 2,
+      "meaning": "读本机指纹失败（ioreg 失败/无该字段）⇒ 同上，放行 + 明确标注（`license request` 以此为结论码）"
+    },
+    "device_algo_unknown": {
+      "exit": 0,
+      "meaning": "许可声明的指纹算法本客户端不认识 ⇒ 无法比对，按 unbound 放行（换算法不破坏老文件）"
+    },
+    "device_mismatch": {
+      "exit": 1,
+      "meaning": "设备码不匹配：`install` 拒绝落盘；运行期在 7 天宽限内 state=grace（放行+上报），超宽限 ⇒ denied"
+    },
+    "rebind_exhausted": {
+      "exit": 1,
+      "meaning": "设备码不匹配且自助重绑 3 次已用尽 ⇒ 拒绝 + 人工指引（服务端按 `license request` 的设备码重签）"
+    },
+    "regression_refused": {
+      "exit": 1,
+      "meaning": "`install`/`renew` 拒绝**倒退**安装：新文件比现役更早到期（stale）或能力/业务线/席位被收窄（narrowed）⇒ 原许可未改动；显式 `--allow-regression` 才放行（换绑不由该码表达：它走 device_mismatch/rebind_exhausted）"
+    },
+    "license_denied": {
+      "exit": 1,
+      "meaning": "**写类 verb** 在 enforce 模式下被许可闸门拒绝（零副作用：没写台账/没落盘/没回写）"
+    },
+    "enforce_off": {
+      "exit": 0,
+      "meaning": "许可闸门逃生阀（`ARGENT_LICENSE_ENFORCE=off`）：**没有做判定**（不读许可、不留证据）⇒ 照常写"
+    },
+    "gate_error": {
+      "exit": 0,
+      "meaning": "闸门自己跑不起来（缺 `scripts/license-gate.mjs` / 输出不可解析 / 超时）⇒ **放行 + 响亮告警**（宁可不拦，不可误停；与 flow-trigger.sh 同口径）"
+    },
+    "missing": {
+      "exit": 1,
+      "meaning": "许可文件不存在（未授权：装上许可前写操作会被拒）—— **不得**降级成 empty（§3.5③ 验收行）"
+    },
+    "bad_signature": {
+      "exit": 1,
+      "meaning": "许可验签失败（文件被改过 / 不是本机这把密钥签的）⇒ 拒绝"
+    },
+    "expired": {
+      "exit": 1,
+      "meaning": "许可已过期且超出宽限期 ⇒ 拒绝（宽限期内是 license_grace）"
+    },
+    "malformed": {
+      "exit": 1,
+      "meaning": "许可文件不是合法许可 JSON（字段缺失 / 时间不可解析）⇒ 拒绝（绝不宽容成永不过期）"
+    },
+    "bad_version": {
+      "exit": 1,
+      "meaning": "许可版本本客户端不认识（当前只认 v1）⇒ 拒绝"
+    },
+    "no_secret": {
+      "exit": 1,
+      "meaning": "本机没有验签密钥（ARGENT_LICENSE_SECRET / license.secret 都没有）⇒ 拒绝，不是“当通过”"
+    },
+    "unreadable": {
+      "exit": 1,
+      "meaning": "许可文件读不出来（权限/IO）⇒ 拒绝"
+    },
+    "cap_not_allowed": {
+      "exit": 1,
+      "meaning": "许可里没有这次要用的能力（capabilities 是白名单：空数组 = 什么都不许）"
+    },
+    "vertical_not_allowed": {
+      "exit": 1,
+      "meaning": "许可不含这条业务线（verticals 空 = 不限，非空则必须显式包含）"
+    },
+    "no_refresh_source": {
+      "exit": 0,
+      "meaning": "`license renew` 没有可用的续期来源（没有新许可文件、也没有在线端点）⇒ **成功但空**，维持原状态"
+    },
+    "duplicate_suppressed": {
+      "exit": 0,
+      "meaning": "通知幂等：同一事实已投递过 ⇒ 成功但**不重发**（empty:true）"
+    },
+    "delivery_failed": {
+      "exit": 1,
+      "meaning": "投递失败（非 2xx / 超时 / 连接失败；不跟随重定向，3xx 也算失败）"
+    },
+    "unknown_channel": {
+      "exit": 2,
+      "meaning": "通知通道名未登记（缺声明）"
+    },
+    "channel_not_implemented": {
+      "exit": 2,
+      "meaning": "通道是**预留位**：端口契约已定、投递实现未落地（绝不假装已发）"
+    },
+    "target_required": {
+      "exit": 2,
+      "meaning": "通道缺目标（webhook 的 --url 等）"
+    },
+    "bad_target": {
+      "exit": 2,
+      "meaning": "目标不是该通道接受的形态（如 webhook 非 http(s)）"
+    },
+    "missing_body": {
+      "exit": 2,
+      "meaning": "通知缺正文（--text/--file/--body-json 三选一都没给，或 --text 是空串）"
+    },
+    "body_unreadable": {
+      "exit": 2,
+      "meaning": "正文文件读不到（路径/权限）"
+    },
+    "bad_body_json": {
+      "exit": 2,
+      "meaning": "--body-json 不是合法 JSON"
+    },
+    "datadir_unwritable": {
+      "exit": 2,
+      "meaning": "数据目录建不出来（`init --apply`；环境问题 ⇒ 补环境而非重试）"
+    },
+    "_activationNote": "一次性激活码兑换（方案《许可自助签发与续期》§9）的短码：服务端错误码在客户端**同名映射**（code_*/no_*/seat_*/device_bound_*/rebind_window_*/payment_required/rate_limited/bad_device 与服务端 §9.3 逐字相同），客户端自己产生的码一律 `activation_` 前缀。映射表唯一实现在 `core/lib/license-activate.mjs#SERVER_ERROR_MAP`/`CLIENT_ERROR_MAP`，由 `scripts/tests/license-activate.test.mjs` 与契约逐条对账（R1e 同一条纪律）。",
+    "code_unknown": {
+      "exit": 1,
+      "meaning": "兑换：激活码不存在（抄错，或不是这台服务器的码）⇒ 在网页/手机端重新生成"
+    },
+    "code_expired": {
+      "exit": 1,
+      "meaning": "兑换：激活码已过期（TTL ≤15 分钟）⇒ 重新生成并**尽快**兑换"
+    },
+    "code_already_redeemed": {
+      "exit": 1,
+      "meaning": "兑换：激活码已被用掉且超出\"同码同机幂等复用窗口\"（24h）⇒ 重新生成；窗口内的同机重放是**幂等复用**，不会给该码"
+    },
+    "code_device_locked": {
+      "exit": 1,
+      "meaning": "兑换：激活码已绑定到**另一台机器**（码被转发/双花）⇒ 在那台机器上兑换，或重新生成"
+    },
+    "code_revoked": {
+      "exit": 1,
+      "meaning": "兑换：激活码被运营撤销"
+    },
+    "code_locked": {
+      "exit": 1,
+      "meaning": "兑换：该码失败尝试超限已锁定 ⇒ 重新生成（并核对该机器的设备码）"
+    },
+    "no_entitlement": {
+      "exit": 1,
+      "meaning": "兑换：账号没有任何有效许可（服务端 §2.2-D 同名）⇒ 先购买/开通"
+    },
+    "no_license": {
+      "exit": 1,
+      "meaning": "兑换：账号没有许可记录 ⇒ 开通"
+    },
+    "license_revoked": {
+      "exit": 1,
+      "meaning": "兑换：账号的许可已被吊销 ⇒ 联系运营"
+    },
+    "capability_not_owned": {
+      "exit": 1,
+      "meaning": "兑换：请求的能力超出账号权益（**签发不扩权**）⇒ 以账号权益为准"
+    },
+    "seat_limit_reached": {
+      "exit": 1,
+      "meaning": "兑换：新设备会超席位上限 ⇒ 解绑旧设备或加席位"
+    },
+    "device_bound_elsewhere": {
+      "exit": 1,
+      "meaning": "兑换：同账号同席位已被另一台设备占用 ⇒ 走重绑或人工解绑"
+    },
+    "rebind_window_expired": {
+      "exit": 1,
+      "meaning": "兑换：首次发现设备不匹配已超过 7 天宽限 ⇒ 人工重绑"
+    },
+    "payment_required": {
+      "exit": 1,
+      "meaning": "兑换：未核账不放行（姿态 A）⇒ 走人工核账"
+    },
+    "bad_device": {
+      "exit": 1,
+      "meaning": "兑换：服务端拒绝了设备码（形状/算法不认识）⇒ 重跑 `argent license request`，别手抄"
+    },
+    "activation_server_unconfigured": {
+      "exit": 2,
+      "meaning": "兑换：没有配置端点（`--server` / `ARGENT_LICENSE_SERVER` / `WHYSHU_API_URL` 都没有）⇒ **无默认地址**，补配置再跑（环境问题，不重试）"
+    },
+    "activation_unauthorized": {
+      "exit": 1,
+      "meaning": "兑换：端点返回 401 —— 兑换端点**不应要求账号令牌**（客户机不登录）⇒ 服务端路由/部署配错了"
+    },
+    "activation_server_error": {
+      "exit": 1,
+      "meaning": "兑换：服务端 5xx（含 `signing_secret_missing`）⇒ 运营处置；稍后可用**同一个码**重试"
+    },
+    "activation_bad_response": {
+      "exit": 1,
+      "meaning": "兑换：服务端响应不可解析，或缺 `licenseFile`/`secret` ⇒ **不得**当成功（先核对服务端版本/契约）"
+    },
+    "activation_server_unreachable": {
+      "exit": 1,
+      "meaning": "兑换：连不上端点（DNS/连接失败）⇒ 查网络与 `--server`；同一个码重试安全"
+    },
+    "activation_timeout": {
+      "exit": 1,
+      "meaning": "兑换：请求超时。**码可能已被消费** ⇒ 用**同一个码**重试（同机幂等复用）；仍不行 ⇒ 运营用 `GET /license/activation-code/:prefix` 查状态"
+    },
+    "activation_denied": {
+      "exit": 1,
+      "meaning": "兑换：服务端拒绝但 reason 不在本词表 ⇒ 原串只进 `serverReason`（**不当判据**）"
+    },
+    "activation_disabled": {
+      "exit": 1,
+      "meaning": "兑换：服务端灰度未开启/已回滚（`ACTIVATION_ENABLED=0`）⇒ **改走人工签发入口**（运营按设备码签一份，再 `license install --file`），不要反复重试"
+    },
+    "signing_secret_missing": {
+      "exit": 1,
+      "meaning": "兑换：服务端未配置 `LICENSE_SIGNING_SECRET`（⛔ 不回退默认串）⇒ 运营处置后重试（同一个码重试安全）"
+    }
+  },
+  "invariants": [
+    "凭证永不过网：跨平面只下发工具名 + 业务参数",
+    "所有写操作有审计；幂等键来自台账",
+    "离线可用：许可宽限期内业务不停摆"
+  ],
+  "mcpShadow": {
+    "purpose": "写类能力的入场券：先在隔离沙箱跑真实 CLI 路径，真台账零改动，逐字段比对一致后才允许真写",
+    "writtenTools": [
+      "argent_claim_shadow",
+      "argent_claim（门禁=影子 verified；confirm=true 才真写）",
+      "argent_writeback（默认 dry-run；守卫在脚本内）"
+    ],
+    "pendingRealWrites": [
+      "report（待接入 flow_failure.py）"
+    ],
+    "isolation": "ARGENT_DATA_DIR → mkdtemp 沙箱（台账/案件/开关都在沙箱内）",
+    "proof": "realUnchanged=true（真台账事件数前后一致）",
+    "comparator": {
+      "tool": "argent_shadow_compare",
+      "method": "同输入两次独立影子跑 → 事件序列逐字段比对（归一化 ts/createdAt/leaseUntil/sessionId 等）",
+      "gate": "diffCount == 0 且两次退出码为 0 ⇒ 放行对应流程的 MCP 真写路径"
+    },
+    "gate": "compareShadow(flow, fixture=true).verified == true ⇒ 才允许真写；否则 gated 拒绝"
+  }
+}