@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/docs/ai/workflow.md

@@ -0,0 +1,139 @@
+# 开发步骤与交付要求
+
+[返回学习入口](README.md) · [范例导读](purchase-example.md)
+
+本页命令在**应用根目录**执行，除非注明“框架根目录”。使用项目安装的 CLI：`pnpm exec cage ...`。项目脚本可简写为 `pnpm gen / pnpm migrate / pnpm dev / pnpm verify`；不要假定机器已全局安装 cage。
+
+## 第一次启动应用
+
+前提是 PostgreSQL 数据库已经存在。框架负责连接与表结构，不负责数据库服务的安装、建库或 Docker 生命周期。
+
+```powershell
+pnpm install
+# 仅首次复制；已有 .env 时编辑原文件，不覆盖配置。
+Copy-Item .env.example .env
+# 在 .env 填写 CAGE_ADMIN_DATABASE_URL，指向已有数据库。
+pnpm exec cage init
+pnpm build:app
+pnpm gen
+# 审查 db/migrations 中的迁移草稿，再执行：
+pnpm migrate
+pnpm dev
+```
+
+`init` 自动创建独立账号与随机密码，填写 APP/READ/MIGRATE 连接和 Cookie 密钥，成功后删除文件中的管理员连接。三个连接使用同一数据库。已有 Cage 集群账号时复用原连接，不能重置其他应用的账号密码。生产环境可由平台直接提供账号连接，不必执行本地 init。
+
+`.env.example` 是配置说明，`.env` 是本机私密配置，二者不混用。CLI 自动加载应用 `.env`，部署环境同名变量优先。API 和 worker 启动需重启后读取变更；不要输出整个 `.env` 排障。
+
+框架仓库首次先在根目录 `pnpm install`、`pnpm build`，再进入 `examples/purchase-admin` 配置。`dev` 不自动执行迁移；生成新迁移后要审查并显式运行 migrate。
+
+## 做一项业务修改
+
+1. 读 AGENTS.md 和[目录规范](project-structure.md)，确认需求落在领域模块、前端模块、组织配置还是框架。先 `pnpm exec cage context "需求关键词"`，按需 `graph search/inspect/path` 定位，确认候选入口后阅读对应源码、范例与测试；证据和边界见[本体上下文指南](ontology-context.md)。发现能力缺口先说明，不编造 API。
+2. 涉及已存在业务含义变化时，**修改前**保存基线。已有 Git 可用提交，也可保存独立本体图文件。
+3. 在所属领域模块写字段、状态、不变量和命令输入；再实现 handler、事件、查询与审批。跨模块反应放 workflows，第三方协议放 integrations。从模块 index 到 domain 总入口逐层导出，避免跨文件 export 名冲突。
+4. `pnpm exec cage check` 检查声明和图规则；`pnpm gen` 更新契约与迁移草稿。聚合和命令填写中文 `description`，需要覆盖时补 `cage.config.json` 的 `graph.labels`（如 `aggregate:Note`、`command:Note.archive`、`capability:Note.export`）。这些名称同时用于图谱和 `/admin` 授权界面；修改后重启 API。不重命名实际能力点来实现翻译。在图谱确认连接与资源生命周期。
+5. 审查数据库变更，特别是非空字段、数据回填、删列和索引。已执行的迁移不可改写。需要落库时显式 `pnpm migrate`。
+6. 页面和表单放 `apps/web/src/modules/<业务>`，从模块公开入口接入 app 导航；依赖生成 contracts，处理失败结果。新增能力由管理员授权，页面按钮可用 `useCan` 控制。
+7. 补足重要业务反例并运行相关验证。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
+
+### 如何保存和比较基线
+
+```powershell
+# 修改前执行，避免后续 gen/analyze 覆盖唯一的旧图。
+pnpm exec cage analyze
+Copy-Item .cage/ontology.json .cage/before-change.json
+# 修改 domain 后执行：
+pnpm exec cage impact --base-file .cage/before-change.json
+# 或与真实可用的 Git 提交比较；下面的 main 应按仓库实际情况替换。
+pnpm exec cage impact --base main
+```
+
+基线文件要保留到验收结束。影响分析用于找到相关命令、约束、审批、查询和候选测试，不能当作不需验证的证明。没有 Git 提交时不要为了让命令成功而擅自创建/推送远端。
+
+## 常见需求的具体改法
+
+| 需求 | 做法 | 必查项 |
+| --- | --- | --- |
+| 增加字段 | 修改 aggregate；按命令更新 input/handler；重新生成 | 是否敏感、是否可选、旧数据如何回填、查询/事件/页面受影响吗 |
+| 增加状态或撤回 | 修改 states 和 command；声明事件及资源处理 | 可达性、非终态出边、审批 cancelOn、CAGE-PAIR-002 |
+| 修改审批 | 修改 route/approval；按需要增加 routable | 负责人/role code、步骤 mode、结论命令、额度和职责分离 |
+| 增加报表 | 声明 query 的 reads、input 和 sql/build | 安全视图、参数化、调用人 read 权限、生成 queries 契约 |
+| 接入第三方 | 声明 connector/op/outbound/inbound；配置运行环境密钥 | 请求响应白名单、幂等、超时、验签、永久/可重试错误和补偿 |
+| 改后台管理配置 | 通过组织模型与系统接口修改 | 防提权、实际授权范围、角色缓存刷新、操作人权限 |
+| 改脚手架 | 先修改标准范例，再同步模板并构建 CLI | 新目录实际创建结果、资料分发、凭证不入包 |
+
+## 前端如何消费框架
+
+```ts
+import { purchaseOrder } from '@app/contracts';
+
+// 普通业务接口使用生成的方法；第二个参数可传当前记录的 version。
+const result = await purchaseOrder.submit(order.id, order.version);
+if (!result.ok) {
+  // 按 code 展示通用原因；DOMAIN_ERROR 还可以按 domainCode 展示业务文案。
+  showError(result.domainCode ?? result.code);
+} else {
+  refreshOrder(result.data);
+}
+```
+
+这是页面事件处理片段，`order/showError/refreshOrder` 由业务页面提供。不要导入 domain 命令在浏览器执行，也不要复制后端权限逻辑。生成契约只包含允许 user 调用的写操作；审批通过通过待办接口进行，而不是自己增加 `purchaseOrder.approve()`。
+
+对自定义 HTTP 协议能力使用 `@yss123/cage-client`；它负责会话、CSRF 和类型化结果。需让多个提交共享幂等键时，按当前客户端接口显式传递同一次业务操作的 key，并在页面阻止重复进行中的提交。生成契约的方法签名以 `packages/contracts/src` 为准，不假设每个命令方法都支持自定义 options。
+
+### 导入和导出属于业务页面
+
+框架提供通用异步接口与任务查询，页面放在哪里由具体业务决定。
+
+- 导出调用生成的 `purchaseOrder.export(params, options?)` 等方法，得到任务；使用 `client.transfer(id)` 或 `useTransfer(id)` 查看进度，完成后通过 `client.transferDownloadUrl(id)` 下载。
+- 导入调用 `client.importCsv('PurchaseOrder.create', csv, { atomic: false })` 等，目标是已声明且支持用户调用的命令；每行执行命令，复用权限和业务校验。该例中的 `items` 等复杂字段需遵守实际 CSV 编码规则，不是任意 Excel 文件自动识别。
+- `atomic: true` 请求整批原子处理，普通逐行导入需展示成功/失败计数及报告。HTTP 202 仅代表接受任务，不能立即提示处理完成。
+- worker 必须运行；任务可能 queued/retrying/failed/expired。下载会再次校验当前权限。导出的系统列和掩码值不能原样回导。
+
+CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入导出](transfers.md)。给新业务做入口时按实际生成的签名调用，不硬编码采购单专属逻辑进框架。
+
+## 工具做什么，结果在哪里
+
+| 命令 | 用途 | 主要输出 |
+| --- | --- | --- |
+| `pnpm exec cage analyze` | 抽取显式声明与源码位置 | `.cage/ontology.json` |
+| `pnpm exec cage check` | 静态检查、注册表与图规则 | 终端 `code/at/reason/fix` |
+| `pnpm exec cage graph` | 启动中文本体图谱 | 默认 `http://127.0.0.1:15418`，按终端地址访问 |
+| `pnpm exec cage context "需求或节点"` | 开发前取得相关子图、原因、源码与候选验证 | 默认终端 Markdown；`--format json --out .cage/context.json` 保存结构化报告 |
+| `pnpm exec cage graph search/inspect/path ...` | 检索候选 / 精确节点 / 关系路径 | 同源中文与证据；每次重新抽取，见[用法](ontology-context.md) |
+| `pnpm gen` | 更新契约、结构说明、迁移草稿 | `packages/contracts/src`、`db/migrations`、`generated`、`.cage/ontology.json` |
+| `pnpm exec cage gen --check` | 只比较需提交的生成物 | 不一致时报 CAGE-GEN；不是实际数据库漂移扫描 |
+| `pnpm exec cage test --only project` | 项目测试 | `.cage/test-results.json` 与终端 |
+| `pnpm exec cage test --only derived` | 声明派生的框架性质测试 | `generated/tests`、同一测试报告 |
+| `pnpm verify` | 汇总门禁 | `.cage/verify.json` |
+| `pnpm exec cage verify --skip-tests` | 执行测试以外的门禁 | 报告标明 `complete: false`，不可称全量通过 |
+| `pnpm exec cage sync` / `sync --check` | 同步/比较 AGENTS 托管区 | 保留标记外的项目自有规则；不自动改写业务代码或学习资料 |
+| `pnpm exec cage budget` | 体积、公共词汇和 unsafe 预算 | 终端 metrics/findings |
+| `pnpm exec cage upgrade --dry-run` | 查看当前目标 CLI 所带升级改动 | 文件修改预览；应先安装正确目标版本 CLI |
+
+`generated/` 和 `.cage/` 是可再生资料；contracts 和迁移是需要审查、提交的生成结果。生成迁移通过最后一个迁移内嵌的结构快照比较，不是创建临时数据库，也不能证明真实库从未被手工改动。
+
+## 验证要与改动匹配
+
+- 文档、文案、可逆的小改动：检查链接、格式、资料分发；不需要重复运行全套数据库测试。
+- 命令/约束/反应变化：针对成功路径及真正的风险增加用例，如越权拒绝、额度边界、资源释放、同事务回滚。不要写只复述实现的测试。
+- 领域结构变化：check、gen、生成一致性、类型检查；有数据库影响时在独立测试库验证迁移和读写。
+- 发布前：按项目要求执行完整 verify/build/test，核对分发包。没有执行的项目明确写出原因。
+
+测试使用真实 PostgreSQL。`CAGE_TEST_DATABASE_URL` 供独立测试集群使用，测试工具会准备角色和临时数据库；不要指向业务/生产集群。没有设置时 testkit 可使用内嵌的真实 PostgreSQL，这与 dev 的固定已有库流程不同。
+
+派生测试无法凭空推断所有业务合法输入，会报告跳过。它们证明的是通用性质，不能代替采购 happy path、审批配置和第三方真实联调。
+
+## 可以交给 AI 的任务描述
+
+```text
+先读 AGENTS.md 和它指定的 docs/ai/README.md，再参考对应标准范例。
+需求：为某业务增加……
+先用 cage context 查询现有业务，必要时 graph inspect/path，确认候选与关系后阅读实现。
+说明字段、状态、能力与范围、事件/资源的影响，再修改 domain、生成契约和迁移草稿、接入业务页面。
+使用真实公开 API；不要手写业务路由、直接写表或新增本地数据库生命周期命令。
+按改动运行必要检查，报告通过/跳过/未执行项和需要的管理员配置。
+```
+
+交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、验证结果，以及尚未做的真实外部联调。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。

package/templates/app/docs/errors/CAGE-APPR-001.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-001：可路由字段不存在
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+approval.routable 引用了所属聚合没有声明的字段。
+
+## 修复步骤
+
+1. 先在聚合声明实际字段，再将需要给审批路由的字段放入 routable；不要把任意输入直接交给流程。
+
+## 正例
+
+```text
+routable: ['amount', 'deptId'] // 两字段均在 PurchaseOrder.fields 中
+```
+
+## 反例
+
+```text
+routable: ['managerName'] // 聚合没有该字段
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:134`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const f of def.routable) {
+    if (!(f in agg.fields)) throw declError('CAGE-APPR-001', `可路由字段 ${agg.name}.${f} 不存在`);
+  }
+  for (const c of [def.onApproved, def.onRejected]) {
+    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+```

package/templates/app/docs/errors/CAGE-APPR-002.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-002：审批结论落到其他聚合
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+onApproved 或 onRejected 的命令不属于当前审批绑定的聚合。
+
+## 修复步骤
+
+1. 把结论绑定到当前单据的命令；后续跨对象动作通过该命令的事件和反应完成。
+
+## 正例
+
+```text
+PurchaseOrder 的审批绑定使用 approvePurchaseOrder 命令
+```
+
+## 反例
+
+```text
+采购审批 onApproved 直接绑定 InventoryLock.acquire
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:137`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const c of [def.onApproved, def.onRejected]) {
+    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+    if (!c.invokedBy.includes('process')) {
+      throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+    }
+```

package/templates/app/docs/errors/CAGE-APPR-003.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-003：审批结论未允许流程调用
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+审批结论命令的 invokedBy 不包含 process。
+
+## 修复步骤
+
+1. 将结论命令声明为 process；前端通过待办接口审批，不要为了显示按钮把结论改成用户可直调。
+
+## 正例
+
+```text
+invokedBy: 'process'
+```
+
+## 反例
+
+```text
+invokedBy: 'user' // 用作审批结论
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:139`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (!c.invokedBy.includes('process')) {
+      throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);
+    }
+  }
+  return Object.freeze({
+```

package/templates/app/docs/errors/CAGE-APPR-004.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-004：路由没有对应审批绑定
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+运行审批桥接时，route 的 process 找不到同名 approval 绑定。
+
+## 修复步骤
+
+1. 检查 process 名完全相同，绑定和路由均从 domain 入口导出。
+
+## 正例
+
+```text
+approval(..., { process: 'po-approval', ... }) 与 route('po-approval', ...)
+```
+
+## 反例
+
+```text
+绑定叫 po-approval，路由叫 purchase-approval
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/bridge.ts:8`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const binding = k.registry.approvalByProcess(r.process);
+  if (!binding) throw new Error(`[CAGE-APPR-004] 没有流程 ${r.process} 的审批绑定`);
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : binding.a.onRejected;
+  const ctx = k.processCtx({
+    process: r.process,
+```

package/templates/app/docs/errors/CAGE-APPR-005.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-005：流程名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+route 的流程标识不是小写字母开头的小写短横线格式。
+
+## 修复步骤
+
+1. 使用稳定的小写短横线标识；需要中文显示时修改 step 标题或图谱 label，不翻译标识。
+
+## 正例
+
+```text
+route('po-approval', nodes)
+```
+
+## 反例
+
+```text
+route('采购审批', nodes)
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/route.ts:96`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function route(process: string, nodes: RouteNode[]): Route {
+  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
+  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
+  const fields = new Set<string>();
+  for (const n of nodes) {
+```

package/templates/app/docs/errors/CAGE-APPR-006.md

@@ -0,0 +1,47 @@
+# CAGE-APPR-006：流程没有步骤
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+route 接收了空步骤数组。
+
+## 修复步骤
+
+1. 声明至少一个实际审批步骤，并检查条件后能否形成预期流程。
+
+## 正例
+
+```text
+route('po-approval', [step('经理审批', approver.deptLeader('deptId'))])
+```
+
+## 反例
+
+```text
+route('po-approval', [])
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/route.ts:97`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
+  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
+  const fields = new Set<string>();
+  for (const n of nodes) {
+    const steps = n.kind === 'step' ? [n] : n.steps;
+```

package/templates/app/docs/errors/CAGE-APPR-007.md

@@ -0,0 +1,50 @@
+# CAGE-APPR-007：找不到审批人
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+worker 启动或推进审批步骤时，选人器没有找到人。
+
+## 修复步骤
+
+1. 先看本项目 approvals.ts：deptLeader 读取单据部门的负责人；role 使用角色 code；user 使用实际用户 UUID。
+2. 在 /admin 设置单据所属部门的负责人，或创建对应 code 的角色并分配实际用户。给用户经理角色，并不等于设置了部门负责人。
+3. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
+4. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
+
+## 正例
+
+```text
+deptLeader('deptId')：给该部门设置负责人；role('finance')：给实际用户分配 code=finance 的角色
+```
+
+## 反例
+
+```text
+只建中文名为“财务”的角色却没有配置 code/用户，或配置后重复提交已是 pending_approval 的单据
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/engine.ts:64`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (who.length === 0) {
+      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${s.title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
+    }
+    for (const assignee of new Set(who)) {
+      await tx.insertInto('flow.approval_task').values({ instance_id: instanceId, tenant_id: tenantId, step: index, title: s.title, assignee }).execute();
+```

package/templates/app/docs/errors/CAGE-APPR-010.md

@@ -0,0 +1,48 @@
+# CAGE-APPR-010：流程专用命令没有调用者
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+命令只允许 process 调用，但图中没有审批结论、反应或任务调用它。
+
+## 修复步骤
+
+1. 补实际 approval/reaction/job 引用并从入口导出；如果本来是用户操作，按需求纠正 invokedBy。不要增加空引用骗过检查。
+
+## 正例
+
+```text
+approve 被 poApproval.onApproved 引用，或 acquireLock 被 lockOnApprove 引用
+```
+
+## 反例
+
+```text
+定义 process 命令但没有任何流程或反应调用
+```
+
+## 修复后验证
+
+先 cage check；涉及选人/流程推进时，用实际用户、部门和角色提交并处理待办，检查 worker 与死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:140`
+- `packages/cli/src/rules.ts:149`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-APPR-010：invokedBy 为 process 的命令必须有审批绑定或反应调用它，否则没有人能调用 */
+export function checkProcessCommands(g: Ontology): Finding[] {
+  const { into } = index(g);
+  const findings: Finding[] = [];
+```

package/templates/app/docs/errors/CAGE-AUTH-001.md

@@ -0,0 +1,47 @@
+# CAGE-AUTH-001：OIDC 发现文档获取失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：HTTP 登录。
+
+HTTP 无法取得 OIDC issuer 的发现文档，或远端返回非成功状态。
+
+## 修复步骤
+
+1. 检查部署环境 OIDC issuer、发现地址、网络与证书配置；不要关闭认证或把 issuer 校验删掉。
+
+## 正例
+
+```text
+配置可访问的 OIDC_ISSUER、正确客户端和回调地址
+```
+
+## 反例
+
+```text
+将不可访问的 issuer 当作已成功登录并继续建立会话
+```
+
+## 修复后验证
+
+重新走真实 OIDC 登录和回调，确认会话中的用户与授权；不要仅验证发现文档能打开。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/http/src/oidc.ts:20`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    (disco ??= fetch(new URL('.well-known/openid-configuration', o.issuer.endsWith('/') ? o.issuer : `${o.issuer}/`)).then(async (r) => {
+      if (!r.ok) throw new Error(`[CAGE-AUTH-001] OIDC 发现文档获取失败：${r.status}`);
+      return (await r.json()) as Discovery;
+    }));
+  const secure = opts.cookieSecure ?? process.env.NODE_ENV === 'production';
+```

package/templates/app/docs/errors/CAGE-BUDGET-001.md

@@ -0,0 +1,47 @@
+# CAGE-BUDGET-001：内核超出体积预算
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：budget / verify。
+
+框架源码检查发现内核有效代码行数超过当前 5000 行预算。
+
+## 修复步骤
+
+1. 框架维护者将非内核职责拆为扩展，必要的预算调整需架构评审。独立业务项目不应复制内核源码来修此错误。
+
+## 正例
+
+```text
+第三方业务放到 connectors/业务声明，内核保持通用
+```
+
+## 反例
+
+```text
+直接调大阈值或删除检查
+```
+
+## 修复后验证
+
+重跑 cage budget；有 unsafe 基线时使用真实受审基线。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/budget.ts:45`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-001',
+      reason: `内核 ${lines} 行，超过 5000 行预算`,
+      fix: '拆出扩展职责，或提交架构评审调整预算',
+    });
+```

package/templates/app/docs/errors/CAGE-BUDGET-002.md

@@ -0,0 +1,47 @@
+# CAGE-BUDGET-002：公共原语超过词汇预算
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：budget / verify。
+
+框架公共词汇计数超过当前 16 个预算。
+
+## 修复步骤
+
+1. 优先组合现有原语；确需增加公共概念时由框架维护者评审，不由业务项目随意扩展品牌。
+
+## 正例
+
+```text
+用 command/event/reaction 组合新业务
+```
+
+## 反例
+
+```text
+每个业务动作新增一个框架原语
+```
+
+## 修复后验证
+
+重跑 cage budget；有 unsafe 基线时使用真实受审基线。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/budget.ts:51`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-002',
+      reason: `品牌原语 ${primitives} 个，超过 16 个预算`,
+      fix: '优先使用组合子，避免新增原语',
+    });
+```