dsh-crwu-workbench 0.0.10

package/skills/crwu/crwu-dev-audit-skill-maintainer/references/05-validation-and-delivery.md

@@ -0,0 +1,127 @@
+# 验证与交付
+
+## 导航
+
+- [检查器](#检查器)
+- [新 Skill 验证](#新-skill-验证)
+- [目录树盘点交付](#目录树盘点交付)
+- [完成判据](#完成判据)
+
+## 检查器
+
+```bash
+python3 scripts/check_audit_skill_mappings.py \
+  --repo-root <source-repo> \
+  --catalog <目录树、snapshot 或 node-index> \
+  --format text
+```
+
+输出 schema 为 `crwu.audit-skill-maintainer.report.v1`。主要 finding：
+
+| 类型 | 级别 | 处理 |
+| --- | --- | --- |
+| `ROUTER_FILE_MISSING` | error | 总路由 `crwu-audit/SKILL.md` 不存在 |
+| `ROUTER_REFERENCE_MISSING` | error | router 依赖的路由 reference 缺失（00/02–08/10/99） |
+| `ROUTER_REFERENCE_UNRESOLVED` | error | router 命名的 `NN-*.md` 在 `crwu-audit/references/` 下不存在 |
+| `ROUTER_AXIS_UNDISPATCHED` | error | 知识库有该轴一级目录，但并集规则从不加载对应输入（`asset_skills`/`business_skills`） |
+| `ROUTER_SKILL_REFERENCE_UNRESOLVED` | error | router 或并集规则命名的具体技能既非真实目录、也非 registry 行 |
+| `REGISTRY_FILE_MISSING` | error | registry 缺失；先恢复 registry 再做其他判断 |
+| `FIRST_LEVEL_SKILL_MISSING` | error | 建议创建或登记父级 Skill |
+| `FIRST_LEVEL_SKILL_PENDING` | warning | 一级能力已登记但未落地；只登记 gap，不建空目录 |
+| `LEGACY_BUSINESS_PREFIX` | error | 制定 `crwu-audit-biz-*` 迁移方案 |
+| `AXIS_PREFIX_MISMATCH` | error | 轴与 Skill 前缀不符；改名或改登记，不得两者都留 |
+| `AVAILABLE_SKILL_DIRECTORY_MISSING` | error | `available` 声明的真实目录不存在；修复或降级状态（含 public 轴行） |
+| `SKILL_NAME_MISMATCH` | error | 目录名、frontmatter 与 registry 名称不一致（含 public 轴行） |
+| `SKILL_REFERENCE_MISSING` | error | available Skill 缺少规定 reference；**public 轴**只要求声明一份 KB 装配表（`01-kb-assembly.md` 或横切能力沿用的 `00-KB装配表.md`），不套用资产/业务叶子的三件套命名 |
+| `REGISTRY_LABEL_DUPLICATE` | error | 一级标签登记多行；合并为恰好一行 |
+| `REGISTRY_LABEL_NOT_IN_CATALOG` | warning | `available` 标签在最新目录中无对应一级目录（改名或失效） |
+| `CLASSIFICATION_LABEL_MISSING` | warning | 一级标签未写入对应 classification |
+| `ORPHAN_SKILL` | warning | source 中存在未登记资产/业务 Skill |
+| `LEGACY_COMBINED_SKILL` | error | 既非已登记轴 Skill、也非 router/维护/横切能力的遗留组合 Skill（如 `crwu-audit-realestate-rent`）；登记或迁移到 `crwu-audit-asset-*`／`crwu-audit-biz-*` |
+| `ASSEMBLY_FILE_MAPPING` | error | 仍逐文件登记；改为一句话递归一级根 |
+| `ASSEMBLY_FIRST_LEVEL_ROOT_MISSING` | error | available Skill 缺少精确一级根或 `directory`/`recursive` 契约 |
+| `MAPPING_ROOT_NOT_IN_CATALOG` | error | 声明的一级根在最新目录中已不存在 |
+| `AXIS_ROOT_MISMATCH` | error | 资产 Skill 登记业务根（或反向），跨轴越界 |
+| `ASSET_COMMON_REFERENCE_MISSING` | error | 知识库内容缺口，不创建子 Skill |
+| `ASSET_SUBOBJECT_REVIEW_MISSING` | warning | 细分对象内容缺口，不创建子 Skill |
+| `BUSINESS_SUBROUTE_REVIEW_MISSING` | warning | 子业务内容缺口，不创建子 Skill |
+| `KB_PATH_KEY_NOT_IN_CATALOG` | error | 技能里写的库内路径键在最新目录中不存在（跨库/改名/编号漂移） |
+| `KB_PATH_KEY_HAS_EXPORT_SUFFIX` | error | 路径键带了 `.md` 导出后缀（或把文件当目录写）；`.md` 只是导出后的本地文件名，不是库内节点名 |
+| `KB_PATH_KEY_FOLDER_NEEDS_SLASH` | error | 路径键指向目录却没以 `/` 结尾（会被当成单文件项而记 failure） |
+| `BUSINESS_COMMON_REVIEW_NOT_REFERENCED` | warning | 一级业务目录存在 `共同审核点`，但该业务 Skill **未以路径键回指**它（必须写出 `<一级根>共同审核点`，节点名可带数字前缀或 `.md`）；仅在该文档确实存在时触发，文档不存在不报。**只提名字不算回指**——写"一级根未提供 `共同审核点`"这种否定句同样会被报出 |
+| `NON_RUNTIME_MODULE_ASSEMBLED` | error | 原型/非运行时知识模块被装入实际审核；满足正式发布、规则编号和维护人等启用条件前移除运行时路径 |
+| `CATALOG_NOT_LIVE` | error | 使用 `--max-age-hours` 时，快照无可解析抓取时间（无法证明是最新） |
+| `CATALOG_STALE` | error | 使用 `--max-age-hours` 时，快照抓取时间超过时限 |
+
+判定边界：
+
+- 每一条资产/业务 registry 行都会被独立校验，即使其 label 不在本次目录快照内；否则目录改名会掩盖 registry 漂移。
+- **公共轴（`public`）行另行校验**：与报告形态无关的公共能力不在 `02-资产类型/` / `01-业务路线/` 一级根模型内，其装配键位于 `06-规则库/` 下且可以多于一个，因此**不适用** `ASSEMBLY_FIRST_LEVEL_ROOT_MISSING`、`ASSEMBLY_FILE_MAPPING`、`AXIS_ROOT_MISMATCH`、`AXIS_PREFIX_MISMATCH` 与 `MAPPING_ROOT_NOT_IN_CATALOG`。适用于它们的是一级目录根之外的完整性检查：目录存在、frontmatter 名一致、声明了一份 KB 装配表；其库内路径键由 `inspect_path_keys` 统一校验（该函数遍历全部 `crwu-audit*` 目录，公共轴天然在内）。
+- `MAPPING_ROOT_NOT_IN_CATALOG`、`AXIS_ROOT_MISMATCH` 和 `REGISTRY_LABEL_NOT_IN_CATALOG` 只在该轴的容器目录（`02-资产类型/`、`01-业务路线/`）已被本次目录捕获时才判定；只抓了一个轴的局部快照不会被误读为另一轴已被删除。
+- `REGISTRY_LABEL_NOT_IN_CATALOG` 只针对 `available` 行；`pending` 行的目录缺失属于正常中间态。
+- 重复 registry 行只按一条主张校验，避免同一问题重复计数。
+
+路径键检查范围：skills 根下 `crwu-audit*` 技能目录全部 `.md` 的**反引号内容**（技能约定寻址键写在反引号里）；只判断**本次目录已捕获的顶层容器**下的键——局部快照不会被误读为"另一轴全失效"。含 `…`／`*`／`<>`／`某`／`待建`／`不存在`／`省略` 的写法视为示例，不检查。
+
+`--emit-map` 的幂等要求：校准表 `07-kb-skill-map.md` 自身就在扫描范围内，因此它写出的「库内路径键健康」诊断表**不得给未命中键加反引号**（否则下一轮会把这张表当成本文件的新漂移，并把别的技能的漂移重复记到维护器名下）。回归见本技能 `scripts/test_audit_skill_maintainer.py::test_emitted_calibration_table_does_not_become_drift`。
+
+`--format json` 的 stdout 纯净：报告是 stdout 上的唯一对象；`--emit-map` 的"校准表已更新"通知在该模式下走 stderr，便于调用方直接解析。
+
+默认发现错误仍退出 0，方便盘点交付；CI 使用 `--strict`，存在 error finding 时退出 1。解析失败或输入不支持退出 2。
+
+## 新 Skill 验证
+
+```bash
+# 以下命令在技能目录内执行（`scripts/` = 本技能自带脚本）；跨技能脚本按**技能层**寻址 ——
+# DSH 一个层就是一个技能根：本技能与 crwu-audit 在自研层，crwu-dws 在公共层（不是同一个根）。
+CRWU_SKILLS_ROOT=<本技能所安装到的自研层>
+COMMON_SKILLS_ROOT=<公共技能层>
+python3 scripts/test_audit_skill_maintainer.py
+python3 <skill-creator>/scripts/quick_validate.py <本技能目录>
+python3 "$CRWU_SKILLS_ROOT/crwu-audit/scripts/test_audit_multiaxis_router.py"
+python3 "$COMMON_SKILLS_ROOT/crwu-dws/scripts/test_dws_source_contract.py"
+python3 scripts/kb_tool.py validate --skill-root "$CRWU_SKILLS_ROOT" --skill-root "$COMMON_SKILLS_ROOT"
+git diff --check
+```
+
+读取完整输出并逐项记录 exit code。迁移中的既有失败与本次回归分开报告；不得删除测试、扩大范围或修改无关文件来制造全绿。
+
+### 条件验证：装配可复现性与案例回归
+
+上面的**通用命令由本文件唯一维护**；再按改动性质追加下面两类条件验证（optimize 与其它技能一律只回指本节，不得各自再定义一份判据或命令）：
+
+1. **装配可复现性**：改动涉及装配表（`references/01-kb-assembly.md`）、装配范围、库内路径键或画像装配时，
+   必须对**受影响装配**做**两跑**导出——按路径键取两次，比较**文件集合**与任务既有的可复现性证据
+   （清单 / 摘要 / `exportedAt`）；**差异必须为空**，否则不得判定完成。
+2. **案例回归**：改动影响已有校准案例时，必须重跑受影响案例；已登记的 `BG8169 / 300673` 在适用时输出
+   必须**不劣化**（劣化即不得完成）。不适用时必须显式写 `N/A` 并给出依据，**不得静默跳过**。
+
+## 目录树盘点交付
+
+报告按以下顺序输出：
+
+1. **结论分级**：已核实最新（本次在线且 complete=true、failures 为空）／候选·待核验（非本次在线、complete=false 或 failures 非空）／无法判定（刷新失败且无可用快照）；
+2. 输入类型、抓取时间、complete 状态和一级目录数量；
+3. 路由机制结论（入口与路由 reference 齐全、知识库出现的轴都已分发）；
+4. 当前完整且映射正确的 Skill；
+5. 建议新增的一级资产、一级业务 Skill（并说明细分对象、子业务、结构缺口**不**进入该清单）；
+6. 需要修复、改名或重映射的 Skill；
+7. 细分对象和子业务的内容缺口，以及一级业务目录 `共同审核点` 的有无与是否已回指；
+8. 只凭目录无法确认、必须下载正文的项目；
+9. 下一步逐文件方案及是否需要用户确认；
+10. 校准表路径与本次刷新结果（表格区自动同步；内容级备注写明"已核"或"未核"）。
+
+每个建议包含 axis、一级 label、建议 Skill 名、一级 kb_root、现状证据和动作。细分对象、子业务只能出现在父级索引或内容缺口中，不能进入“新增 Skill”列表。
+
+## 完成判据
+
+- 检查器对 Markdown、`node-index.json` 和 `目录快照.json` 三种真实输入的路径结论完全一致；
+- `catalog.complete=false` 时只输出候选与待核验项，不得据此确认删除、改名或 `available`；
+- 一级根与 registry 一一对应；
+- available Skill 真实存在且 references 完整；
+- 资产共性参考、细分审核条目、业务审核要点已覆盖或明确记 gap；
+- 一级业务目录存在 `共同审核点` 时，该文档已随一级根下载并在 `02-review-focus.md` 回指；不存在时如实记录"未发现"，不记缺口；
+- `07-kb-skill-map.md` 已用本次快照刷新，校准历史追加了一行，内容级备注与本次正文核对结论一致；
+- 库内路径键检查为 0 未命中（含公共轴 `00-总纲`/`03`/`04`/`06` 的键）；有未命中时先修键再谈内容；
+- Skill source 不含知识库名称、个人绝对路径、nodeId 值、下载正文或凭据；
+- 所有验证结果真实报告，提交范围不包含用户的无关改动。

package/skills/crwu/crwu-dev-audit-skill-maintainer/references/06-live-routing-reconciliation.md

@@ -0,0 +1,136 @@
+# 实时路由一致性核对
+
+## 为什么单独一层
+
+`audit` 原本只能证明"某份目录快照与当前登记一致"，不能证明"这份快照还是最新的"。钉钉侧一旦改名、新增或删除一级目录，基于旧快照的结论就会把"已失效"读成"正常"，把"该新建"读成"已覆盖"。
+
+因此本层强制：**先用 `crwu-dws` 拉取最新知识库目录，再与当前 skill 体系逐项对比**，结论必须能追溯到本次抓取时间。
+
+## 步骤一：拉最新目录（经 `crwu-dws`）
+
+- 只读：走 `crwu-dws` 的 M1 目录查询，或 M3 刷新路径；对钉钉零写（`crwu-dws/SKILL.md` §2 白名单）。
+- 缓存只用于定位加速：缓存身份（`.cache-meta.space` 的 name+workspaceId）与本次目标库不一致时，先清理缓存、再在线重下目录结构（`crwu-dws` §5.0）；**不得把旧缓存当作"最新"**。
+- 记录四项：`fetchedAt`（抓取时间）、`complete`、`failures`、一级目录清单。
+- 把本次结果落成本次临时快照（`目录快照.json` / `node-index.json` / `目录树.md` 任一形态），供检查器读取。
+- 同一知识库的三种形态必须给出**完全相同的路径集合**；出现分歧说明解析有问题，不是知识库有差异。
+- 在线刷新失败 → 不进入"已核实最新"结论；只能用旧快照输出**候选**，并显式标注"目录非本次在线结果"。
+
+## 步骤二：与当前 skill 体系逐项对比
+
+| 对比方 | 位置 | 角色 |
+| --- | --- | --- |
+| 知识库 | 本次最新目录 | **唯一路径事实** |
+| 路由机制 | `crwu-audit/SKILL.md` + `references/08-union-dispatch-rules.md` | 分发与并集规则 |
+| 路由参考 | `references/02`~`06` classification + `references/07-skill-registry.md` | 标签与登记 |
+| 真实 Skill | skills 根下的 `crwu-audit*` 技能目录及其 references | 实现事实 |
+| 分类表 | `03-asset-classification.md` / `04-business-classification.md` | 一级标签与二级识别规则 |
+
+## 步骤三：四类检查
+
+### 1 路由机制是否完好
+
+- router 入口 `<skills 根>/crwu-audit/SKILL.md` 存在（否则 `ROUTER_FILE_MISSING`）。
+- router 依赖的路由 reference 齐全：`00-input-and-route-profile.md`、`02`~`06` classification、`07-skill-registry.md`、`08-union-dispatch-rules.md`、`10-capability-gap-proposal.md`、`99-maintenance.md`（缺失 → `ROUTER_REFERENCE_MISSING`）。
+- router 命名的 `NN-*.md` 必须真实存在于 `crwu-audit/references/`；叶子自有 reference 名（`00-applicability.md`/`01-kb-assembly.md`/`02-review-focus.md`）不计（未解析 → `ROUTER_REFERENCE_UNRESOLVED`）。
+- 知识库里出现的轴，并集规则必须真的会加载它：资产 → `asset_skills`，业务 → `business_skills`（缺 → `ROUTER_AXIS_UNDISPATCHED`）。
+
+### 2 路由参考是否注册
+
+- 每个知识库一级目录 → registry **恰好一行**：0 行 = 未登记（`FIRST_LEVEL_SKILL_MISSING`）；多于 1 行 = 重复（`REGISTRY_LABEL_DUPLICATE`）。
+- registry 的 label 必须与知识库一级目录同名（比较时去掉数字排序前缀，写映射时保留完整路径）。
+- 该 label 必须出现在对应 classification（缺 → `CLASSIFICATION_LABEL_MISSING`）。
+- `available` 行必须在真实目录、references、一级根契约上全部成立。
+- registry 声称 `available`、而知识库已无该一级目录 → `REGISTRY_LABEL_NOT_IN_CATALOG`（改名/迁走）。
+
+### 3 Skill 是否存在
+
+- `available` → 目录存在（否则 `AVAILABLE_SKILL_DIRECTORY_MISSING`）+ 三份规定 reference（否则 `SKILL_REFERENCE_MISSING`）+ 名称一致（否则 `SKILL_NAME_MISMATCH`）。
+- 一级根契约：声明的一级根必须精确存在（否则 `ASSEMBLY_FIRST_LEVEL_ROOT_MISSING`）、必须属于本轴（否则 `AXIS_ROOT_MISMATCH`）、必须仍在最新目录中（否则 `MAPPING_ROOT_NOT_IN_CATALOG`）。
+- router 与并集规则里出现的**具体技能名**，必须能解析到真实目录或 registry 行（否则 `ROUTER_SKILL_REFERENCE_UNRESOLVED`）。通配写法（`crwu-audit-asset-*`）与占位写法（`crwu-audit-<axis>-<label>`）不算具体名字。
+- 遗留组合技能与遗留前缀 → `LEGACY_COMBINED_SKILL` / `LEGACY_BUSINESS_PREFIX`，属迁移项，不属"当前可用能力"。
+
+### 4 是否需要创建
+
+- 知识库一级目录没有 registry 行 → **创建候选**（一级资产/业务 Skill），并给出建议名与一级根。
+- 细分对象（如土地使用权）与子业务（如租赁与租金评估）→ **不建 Skill**；进入父级 Skill 的二级索引或内容 gap，绝不能出现在"需创建"清单里。
+- 知识库结构缺口（资产缺 `01-共性参考`、细分对象缺 `评估审核条目`、子业务缺 `01-业务通用审核要点`、业务一级根缺 `共同审核点`）→ 记内容 gap，不新建 Skill。
+- `pending` → 只在 registry 记录，不创建空 Skill 目录。
+
+### 5 方法层 / 清单类是否有人装配（`ASSEMBLY_GAP_METHOD_LAYER`）
+
+方法轴技能（`crwu-audit-method-*`）为 `pending` 期间，方法层与清单类内容**可由命中叶子的装配表承载，
+也可由 router 依据本次 `methods[]`、`overlays[]`、`business_types[]` 与显式跨轴条件动态追加**
+（即 `08-union-dispatch-rules.md` 的方法层/覆盖层/财务报告映射）。上述三类都是**合法装配来源**；
+**"方法轴 pending"不等于"内容可以不装"**。本类检查专门抓"知识库有、三类合法来源的路径键都没覆盖"：
+
+| 库内层级路径（模式） | 期望承载方 | 未覆盖时的判定 |
+| --- | --- | --- |
+| `06-规则库/清单-M-市场法/` | router 的 `method=市场法 ∧ asset=房地产` 跨轴条件映射 | `ASSEMBLY_GAP_METHOD_LAYER` |
+| `06-规则库/清单-M-成本法/` | router 的 `method=成本法` 独立装配映射；不得与资产基础法共用清单 | `ASSEMBLY_GAP_METHOD_LAYER` |
+| `03-评估方法/00-评估方法准则2019-精编/评估方法准则2019-精编条目/` | router 对应方法映射中的准则条目 | `ASSEMBLY_GAP_METHOD_LAYER` |
+| `03-评估方法/01-市场法/`、`05-审核要点/` | router 的 `method=市场法` 与“任一方法命中”映射 | `ASSEMBLY_GAP_METHOD_LAYER` |
+| `03-评估方法/02-收益法/`、`03-资产基础法/`、`04-方法选择/` | router `08-union-dispatch-rules.md` 的对应方法映射：`method=收益法`、`method=资产基础法`、任一 `methods[]` 命中（`04-方法选择/` 归"选择、差异处理与结论一致性"） | `ASSEMBLY_GAP_METHOD_LAYER` |
+| `06-规则库/易错点库/` | 公共通用准则技能的恒装配路径 | `ASSEMBLY_GAP_METHOD_LAYER` |
+
+判定口径：**对全部合法装配来源的路径键取并集**——命中叶子 `references/01-kb-assembly.md`、
+横切技能 `references/00-KB装配表.md`、router `08-union-dispatch-rules.md`（方法层/覆盖层/财务报告条件映射）；
+覆盖可以是该目录本身，也可以是其中任一单文件路径键。**只看键集合，不看正文**（正文由 crwu-dws 实时下载）。
+
+同时检查**通道可导性**：被覆盖的目录若含原生（非 `adoc`）节点，而下载规范未声明对应通道
+<!-- crwu-cli-guard:exempt-next -->
+（历史记录：当时以 `dws drive +download` 或 `dws markdown fetch` 取正文），记 `EXPORT_CHANNEL_UNDECLARED`
+（2026-09-15 前的实测失效：`03-评估方法/**` 整批因通道判定缺失而静默失败，并因此漏装整套市场法清单）。
+
+### 6 原型 / 非运行时模块是否被显式隔离
+
+目录存在不等于内容已达到可执行规则状态。下列目录当前登记为 `prototype/non-runtime`：
+
+- `06-规则库/M-收益法/`：模块规程仍为原型，规则依据含“待编”占位，不能作为正式审核依据；
+- `06-规则库/M-法律法规合规/`：模块规程仍为原型，A 级规则未发布且规则依据待编，不能作为正式合规依据。
+
+检查器必须在 JSON、文本报告和校准表中显式列出命中的路径，但不得把它们计作运行时装配缺口，也不得因为“目录已识别”而把它们加入 router。
+
+如果任何装配表或 router 将任一上述目录加入运行时，记 `NON_RUNTIME_MODULE_ASSEMBLED`（error）。只有知识库将状态改为正式、补齐规则编号并明确维护人，且维护者重新读取正文、完成人工复核后，才能移除隔离并设计正式映射；目录内容自行变化不会自动启用。
+
+## 结论分级（必须标注）
+
+| 结论 | 成立条件 |
+| --- | --- |
+| 已核实最新 | 本次在线抓取成功且 `complete=true`、`failures` 为空 |
+| 候选 / 待核验 | 快照非本次在线结果、`complete=false` 或 `failures` 非空 |
+| 无法判定 | 在线刷新失败且无可用快照 |
+
+## 与各模式的关系
+
+- `audit`：本层就是主流程——先拉最新，再对比，最后按上表标注结论级别。
+- `create` / `remap`：本层是前置，必须刷新后才形成方案。
+- `repair`：改名、结构或边界修复前必须刷新，否则会按过期目录"修"出新漂移。
+- 任何模式都不得只凭旧缓存、历史摘录或他人粘贴的目录下"是否需要创建"的最终结论。
+
+## 命令
+
+```bash
+python3 scripts/check_audit_skill_mappings.py \
+  --repo-root <source-repo> \
+  --catalog <本次 crwu-dws 刷新落地的快照> \
+  --max-age-hours 1 \
+  --format text
+```
+
+`--max-age-hours` 让"必须是最新"可执行：快照没有可解析抓取时间 → `CATALOG_NOT_LIVE`；超过时限 → `CATALOG_STALE`。离线盘点时可省略该参数，但结论必须降级为"候选/待核验"。
+
+## 输出要求
+
+1. 抓取时间、`complete`、`failures` 与一级目录数量；
+2. 路由机制结论（入口/参考齐全、轴已分发）；
+3. 注册一致性（未登记、重复、label 不符）；
+4. 技能存在性（目录、references、一级根）；
+5. 需创建清单，以及**明确不需要创建**的项（细分对象、子业务、结构缺口）；
+6. 结论分级与下一步逐文件方案。
+
+## 红线
+
+- 不得用"缓存命中"冒充"已核实最新"。
+- 不得仅凭快照的"缺席"删除或改名 Skill；删除必须基于最新完整目录并取得用户确认。
+- 不得把细分对象、子业务或知识库结构缺口列进"需创建 Skill"。
+- 不得因在线刷新失败就把旧结论标为最新。