dsh-punky-swarm 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.4.3（2026-09-07）
+
+### 调用级护栏拒绝可见性
+
+- 护栏拦截明示：工具调用送入人工审批后被拒绝（含审批服务不可达、无可用 agent 等降级情形）时，Agent 收到的拒绝不再只是「用户拒绝了该工具」的泛化提示，而会携带护栏标注、命中规则、违规说明与查阅路径——Agent 与用户均可识别该拒绝源于护栏对疑似敏感数据调用的拦截，并可按违规说明修正参数后重发合规调用；非拦截场景行为保持不变。
+- 拒绝文本携带命中规则：拒绝原因末尾追加命中规则及其预设归属（如 L1-A10 · preset l1-sensitive），人工审批请求与直接拒绝路径均携带，用户在批准/拒绝前即可核对所触发的具体规则。
+- 行为说明同步：拒绝可见性语义（拦截明示与规则引用，含边界说明）随双语主题文档 guardrails-hook 同步更新。
+
+### 护栏预设逐条审阅清单
+
+- presets/hook-rules/README.md 新增逐条规则审阅清单：敏感数据防护 12 条与资源边界 6 条，按规则编号 / 预设归属 / 类别 / 生效原语 / 触发工具 / 匹配摘要 / 违规说明逐条成表，供用户与 Agent 主动审阅护栏规则全集；配套一致性断言守护清单与规则文件同步。
+
+### 发布整理
+
+- 版本 0.4.2 → 0.4.3；变更记录整理与发布前内部口径清查。
+
 ## 0.4.2（2026-09-06）
 
 ### 治理配置面板：Lane 过期检测与重派探针
@@ -29,7 +45,7 @@
 ### Web UI 治理配置页 + runtime.json 写通道
 
 - 治理配置设置页（Web UI 设置区）：护栏开关、规则预设、违规自动升级（触发次数 / 窗口）可视化配置；页面保存即时生效、无需重启。
-- runtime.json 热写通道：保存请求经 config-trust 校验（顶层白名单 / 值域 / preset 与内联规则冲突守卫）后落盘 runtime.json，400 校验拒绝不回写；窗口秒输入后端毫秒归一化（windowSeconds → windowMs，线协议键不落盘）。
+- runtime.json 热写通道：保存请求经 config-trust 校验（顶层白名单 / 值域 / preset 与内联规则冲突守卫）后落盘 runtime.json，400 校验拒绝不落盘；窗口秒输入后端毫秒归一化（windowSeconds → windowMs，线协议键不落盘）。
 - 随包双语主题文档：docs/webui-governance-config(.en).md。
 
 ### lane_longrun 超时无进展探针
@@ -99,17 +115,17 @@
 
 ## 0.3.3（2026-08-22）
 
-### 国标 AIP 兼容契约对齐（aip-gb-fix → aip-align-publish 合入主仓库）
+### 国标 AIP 兼容契约对齐
 
-- **aip.enabled 默认开启**（readCapability 合并 `{enabled:true}`）；智能体描述改为 ACS 字段集（P4，根对象 20 键 必填 14/可选 6、AgentSkill 8 键，协议 02.01，旧 14+8 属性降级为 toLegacyDescriptor 兼容映射层）；消息映射对齐 ACPs AIP（P6，aip-format.js Message/TaskCommand/Session 三函数，mailbox/batch 附 ACPs 投影）；身份体系（P2/P3，默认关）：AIC 身份码（前缀 1.2.156.3088 + CRC-16/CCITT-FALSE + Base36）+ CAI 身份证书 + 可插拔签名（默认 ECDSA-P256/RSA-2048）；发现服务（P5/ADP，默认开）：`lib/discovery/` 新域 + `POST /api/dsh-punky-swarm/discover`（type 四类/filter 34 运算符/错误码 40000~40005/50001）+ `GET /.well-known/aip`；P7 工具 6 属性保持现状（待正式文本校准）。
+- **aip.enabled 默认开启**（readCapability 合并 `{enabled:true}`）；智能体描述改为 ACS 字段集（根对象 20 键 必填 14/可选 6、AgentSkill 8 键，协议 02.01，旧 14+8 属性降级为 toLegacyDescriptor 兼容映射层）；消息映射对齐 ACPs AIP（aip-format.js Message/TaskCommand/Session 三函数，mailbox/batch 附 ACPs 投影）；身份体系（默认关）：AIC 身份码（前缀 1.2.156.3088 + CRC-16/CCITT-FALSE + Base36）+ CAI 身份证书 + 可插拔签名（默认 ECDSA-P256/RSA-2048）；发现服务（ADP，默认开）：`lib/discovery/` 新域 + `POST /api/dsh-punky-swarm/discover`（type 四类/filter 34 运算符/错误码 40000~40005/50001）+ `GET /.well-known/aip`；工具描述 6 属性保持现状（待正式协议文本校准）。
 
-### ACPs 通讯方式（P1-P3，默认关）
+### ACPs 通讯方式（默认关）
 
-- **能力总开关默认关（U-D2）**：`acps.enabled` 与 `acps.endpoint.enabled` 均默认 `false`，关闭时零运行时路径；对外 mTLS 服务端点（P1）：独立 HTTPS 监听器（node:https/tls 原生、零新依赖），默认端口 9443/host 127.0.0.1、TLSv1.3 + 双向证书（CERT_REQUIRED）、端点 `POST /acps/rpc`（AIP JSON-RPC）+ `GET /.well-known/acs.json`（ACS 14 必填键 + mutualTLS + JSONRPC）+ `GET /health`，证书 CA 自签（CN=AIC/SAN=acps://AIC，默认 `<root>/acps/certs`）；内部桥接（P2，默认关）：`acps.bridge`（同进程双向，inbound 默认关 D14 需显式 `acps.bridge.inbound=true`；outbound = mailbox→ACPs 投影/投递；`/rpc→bridge 接线` DEF-V6-1，inbound=false 时协议级 rejected INBOUND_DISABLED）；registry 对接（P3/R1 半自动注册，默认关）：login→upsertAgent→submitAgent（人工工批不自动跳过）→requestEab→queryAcs，EAB macKey **AES-256-GCM 加密存证**（D13，与参考实现 SM4-CBC 标注差异）；discovery 对接（P3/DS1 ADP 客户端，默认关）：`POST {baseUrl}/discover` 查询外部 Agent（type 四类/34 运算符与本地共享协议常量），scope=local/external/both（默认 local）；能力注册表扩至 9 键（aip/identity/discovery/verify/watch/worktree/budget/trajectory/**acps**，acps 与 identity 为默认关能力）；未实现项如实标注（P4 工具调用待正式文本；SM2 签名无参考证据可插拔；DS3 mini-ADSP 仅预留签名；V2/V4 与参考实现真实互通待 demo 验证）。
+- **能力总开关默认关**：`acps.enabled` 与 `acps.endpoint.enabled` 均默认 `false`，关闭时零运行时路径；对外 mTLS 服务端点：独立 HTTPS 监听器（node:https/tls 原生、零新依赖），默认端口 9443/host 127.0.0.1、TLSv1.3 + 双向证书（CERT_REQUIRED）、端点 `POST /acps/rpc`（AIP JSON-RPC）+ `GET /.well-known/acs.json`（ACS 14 必填键 + mutualTLS + JSONRPC）+ `GET /health`，证书 CA 自签（CN=AIC/SAN=acps://AIC，默认 `<root>/acps/certs`）；内部桥接（默认关）：`acps.bridge`（同进程双向，inbound 默认关需显式 `acps.bridge.inbound=true`；outbound = mailbox→ACPs 投影/投递；`/rpc→bridge 接线` 已通，inbound=false 时协议级 rejected INBOUND_DISABLED）；registry 对接（半自动注册，默认关）：login→upsertAgent→submitAgent（人工工批不自动跳过）→requestEab→queryAcs，EAB macKey **AES-256-GCM 加密存证**（与参考实现 SM4-CBC 标注差异）；discovery 对接（ADP 客户端，默认关）：`POST {baseUrl}/discover` 查询外部 Agent（type 四类/34 运算符与本地共享协议常量），scope=local/external/both（默认 local）；能力注册表扩至 9 键（aip/identity/discovery/verify/watch/worktree/budget/trajectory/**acps**，acps 与 identity 为默认关能力）；未实现项如实标注（工具调用待正式协议文本校准；SM2 签名无参考证据可插拔；mini-ADSP 仅预留签名；与参考实现真实互通待 demo 验证）。
 
-### 护栏根治 + 文档补建（aip-acps-cleanup）
+### 护栏根治 + 文档补建
 
-- T2.6 护栏 `\r?\n` 修复（merge-agent 护栏）；`README.en.md` 英文文档补建（22 KB，含中文互链）。
+- 护栏 `\r?\n` 处理修复（merge-agent 护栏）；`README.en.md` 英文文档补建（22 KB，含中文互链）。
 
 ## 0.3.2（2026-08-22）
 
@@ -121,15 +137,15 @@
 
 ### 许可合规修正 + npm 发布
 - 许可唯一化：全仓表述统一为 AGPL-3.0 唯一许可（AGPL-3.0-only），移除商业授权字段；其他授权一律「联系作者获得许可」（README.md / README.en.md / CHANGELOG 0.3.0 记载 / docs/OPENSOURCE.md）
-- 品牌残留清零：Swarm 集群品牌词全包改写为 dsh 语义历史沿革（README 中英 L22、SKILL.md L152/L195、CHANGELOG 历史记载）
+- 品牌残留清零：Swarm 集群品牌词全包改写为 dsh 语义历史沿革（README / SKILL.md / CHANGELOG 历史记载）
 - npm 发布：dsh-punky-swarm@0.3.1 发布至 npm registry（`npm install -g dsh-punky-swarm`），README / docs/OPENSOURCE 安装章节同步更新
-- 本地库同步：D:\dsh\Punky-plugin 与发布包文本/版本号对齐（排除 backup/node_modules/backups）
+- 发布包与主仓库文本/版本号对齐（排除备份与依赖目录）
 - 审计清理：docs/OPENSOURCE.md checklist LICENSE 项修正为 AGPL-3.0；本地库 package-lock.json root license 修正为 AGPL-3.0-only
 
 ## 0.3.0（2026-08-21）
 
-### 0.3.0 发布：8 批次升级 + AGPL-3.0 唯一许可 + 治理能力默认全开
-- 8 批次能力升级：引擎修复（目录 consume 判定 / 产物根指引 / 难度门禁豁免）+ lib 四域解耦（43 文件，删 3 单体）+ 国标 AIP 兼容 + 7 能力域（资产/装配/桥接/通信/面板/状态/验证/监控）+ 生命周期 + 恢复机制
+### 0.3.0 发布：AGPL-3.0 唯一许可 + 治理能力默认全开
+- 能力升级：引擎修复（目录 consume 判定 / 产物根指引 / 难度门禁豁免）+ lib 四域解耦（43 文件，删 3 单体）+ 国标 AIP 兼容 + 7 能力域（资产/装配/桥接/通信/面板/状态/验证/监控）+ 生命周期 + 恢复机制
 - 测试 93 → 276 全绿（27 测试文件）
 - 许可切换：Apache-2.0 → AGPL-3.0 唯一许可（AGPL-3.0-only；其他授权一律联系作者获得许可，自 0.3.0 起）
 - 治理能力默认全开：wavePlan 三层 DAG + 引擎级门禁 + 状态机 + 锁/mailbox + 会话隔离
@@ -148,7 +164,7 @@
 - 新增 SKILL.md「Manager 角色派发模板」：Manager=代劳指挥（只指挥不执行、不派发子代理），指挥循环 5 步（batch_status 读黑板 → mailbox_send 建议派发 → mailbox_read 收通知 → member_status/settle 结算 → report 批次完成）；任务包模板补 worker 双通道回执约定（report→Leader 简短 + mailbox_send outbox→Manager 详细）
 - 新增 persona 纪律 0g Leader 唤醒协议：worker 由 Leader 派发（depth-1 直系）、Manager mailbox 建议、report→send_message 一行唤醒、Leader 不做调度决策（调度循环在 Manager 上下文）
 - manager.md 协作方式 5 要素更新：不派发子代理 / mailbox 建议派发 / 收 worker 通知 / member_settle 结算裁决 / worker 双通道回执
-- references/ 残留清零：constitution/workflow/call-chain-matrix-template/leader-decision-pack 4 文件 Swarm 集群运行时术语（HITL/HATL/Converge/任务包）改写为 dsh 语义（人审门禁/gap-list 对账/lane 任务）；role 8 文件重写（4 段骨架 dsh 工具面对齐）
+- references/ 残留术语改写：Swarm 集群运行时术语（HITL/HATL/Converge/任务包）统一为 dsh 治理语义（人审门禁/gap-list 对账/lane 任务）。
 - 测试 93/93 全绿；安装链路验证（模块加载 + syncAssets 幂等）通过
 
 ## 0.2.0（2026-08-19）

package/cordis.patch.yml

@@ -31,7 +31,7 @@
           #   intervalsMinutes 退避档位（分钟，默认 [10,20,30]，冷场越久追问间隔越长）；maxMissed 硬停拍数
           #   （默认 3，连续 N 拍无活动 → appendEvent('lane.stalled') 停止追问，只标记不自动处置）；
           #   scanIntervalMinutes watchdog 扫描间隔（默认 1）；probeTemplate 可选覆写追问模板（{lane}/{batchId}/{missed} 占位）。
-          #   longrun 子键（长跑档探针，出厂默认开——用户定案修订，非设计默认关）：running lane 持续超
+          #   longrun 子键（长跑档探针，出厂默认开）：running lane 持续超
           #   maxDurationMs（默认 1200000=20min）且近 noProgressWindowMs（默认 300000=5min）无新 checkpoint
           #   且无活动（严格 AND）→ 同 tick 产 lane.longrun.candidate 事件 + mailbox broadcast 候选通知
           #   Manager 裁决（探针只标记不改 lane 状态；lane_longrun 工具并列注册，enabled=false 不注册、
@@ -39,12 +39,12 @@
           watch:
             enabled: true
             longrun:
-              enabled: true           # 出厂默认开（定案修订：显式 false 才关）
+              enabled: true           # 出厂默认开（显式 false 才关）
               maxDurationMs: 1200000  # 长跑超时阈值（默认 20min；正整数 ms，非法回退默认）
               noProgressWindowMs: 300000  # 无进展窗（默认 5min；正整数 ms，非法回退默认）
           # worktree 物理隔离（lane-tools）：enabled=true 时注册 lane_worktree_create / lane_worktree_merge / lane_checkpoint
           # （git worktree 隔离 + checkpoint 提交；与 lane_claim 逻辑锁互补——lane_claim 管状态层「写谁的」，
-          #  本组工具管工作区层「写到哪」；工具总数按 register.js TBD-2 实测口径：裸配置 20 / patch 全开 21（含 lane_longrun 与 lane_checkpoint_status）/ 显式关（worktree+watch 关）14）。
+          #  本组工具管工作区层「写到哪」；工具总数：裸配置 20 / patch 全开 21（含 lane_longrun 与 lane_checkpoint_status）/ 显式关（worktree+watch 关）14）。
           worktree:
             enabled: true
             # merge agent 装配键：enabled=true 且宿主注入 mergeAgentSpawner 时，
@@ -66,28 +66,28 @@
           #   落盘到引擎产物根（可审计）；显式 enabled:false 可关闭（关闭时工具不注册）。
           logs:
             enabled: true
-        # 工具调用级护栏（governance hook，M2 阶段 2.2）：订阅宿主 tools/pre-execute + tools/post-execute，
+        # 工具调用级护栏（governance hook）：订阅宿主 tools/pre-execute + tools/post-execute，
         # 6 原语纯函数内核（ALLOW/DENY/REQUIRE_APPROVAL/DEFER/NARROW/PAUSE）；拒绝收据落盘
         # <root>/governance/refusals/<sessionId>/。rules 空表=零拦截（decide 恒 ALLOW，行为不变）。
-        # 分层：任务级=ctx.tools.guard 难度门禁（core.js:65，派发前治理）；调用级=本 hook（执行时治理）。
-        # 【已敲定 2026-08-31】默认开启（hook.enabled: true），可显式关闭（governance.hook.enabled=false）。
-        # 热更新（P3 已热切，harden-plan §5.4 A）：governance 键已纳入 runtime.json 白名单
-        # （lib/hot/config-watch.js ALLOWED_TOP_KEYS）——governance.hook 任一子键生效变化（enabled 翻转 /
-        # rules / flags / defaults）经 applyConfigChange ⑤ dispose+重挂即时生效，免重启；
+        # 分层：任务级=ctx.tools.guard 难度门禁（派发前治理）；调用级=本 hook（执行时治理）。
+        # 默认开启（hook.enabled: true），可显式关闭（governance.hook.enabled=false）。
+        # 热更新：governance 键已纳入 runtime.json 热更白名单
+        # ——governance.hook 任一子键生效变化（enabled 翻转 /
+        # rules / flags / defaults）经热更 dispose+重挂即时生效，免重启；
         # <root>/config/runtime.json 覆盖示例见 README（如 {"governance":{"hook":{"enabled":false}}}）。
         governance:
           hook:
             enabled: true      # 默认开启；空规则表 → decide 恒 ALLOW → 零行为变化
             rules: []          # 规则表（空=零拦截）；Rule 结构见 lib/governance/types.ts
-            # M5-b preset 装载键（preset-build）：引用随包预设（presets/hook-rules/ 三 JSON，注册 id 枚举：
+            # preset 装载键：引用随包预设（presets/hook-rules/ 三 JSON，注册 id 枚举：
             #   l1-sensitive / l2-resource / compose——不接受任意路径），保序展开拼接至 rules（inline rules 在后）。
             #   preset: 'l1-sensitive' 或 preset: ['l1-sensitive', 'l2-resource']（= compose 逐条等价，二选一互斥引用——
             #   同批引用 compose + l1-sensitive 会产生重复 id → 装载失败回退空表 + warn，宁空勿半）。
-            #   runtime.json 热更示例：{"governance":{"hook":{"preset":["l1-sensitive","l2-resource"]}}}（⑤ 通道即时生效）。
+            #   runtime.json 热更示例：{"governance":{"hook":{"preset":["l1-sensitive","l2-resource"]}}}（热更即时生效）。
             #   出厂不默认启用任何 preset（本键缺省 = 空表零拦截不变，与 rules:[] 出厂安全默认严格一致）——
             #   需启用时经 runtime.json 下发或装配 config 注入；preset 文件内容随包版本发布生效（boot 装载一次）。
             # preset: []        # ← 示例注释（默认不启用，勿取消注释即默认值）
-            # M5-a：护栏违规计数升级（默认关——出厂零行为变化；开启后：归属批次的规则拒绝
+            # 护栏违规计数升级（默认关——出厂零行为变化；开启后：归属批次的规则拒绝
             # （DENY/NARROW）在 windowMs 内达 threshold → 经棘轮校验批 paused（reason=governance-escalate）；
             # 与 hook enabled:true 内核就位零拦截正交——出厂 rules:[] 本就零收据，关保持「改规则不意外武装暂停」保守面）
             escalation:
@@ -96,9 +96,9 @@
               windowMs: 600000 # 滚动计数窗口（毫秒，≥1000；10 分钟）
               primitives: [DENY, NARROW]  # 计入原语子集（可扩入 DEFER/PAUSE；REQUIRE_APPROVAL 与状态门收据不可配）
             defaults:
-              deny: DENY       # fail-closed 兜底（未分类违规 → 兜底原语，hf.md:87）；可配置为其他拒绝类原语
-                               # （如 REQUIRE_APPROVAL）；不可为 ALLOW——resolve 校验回退 DENY（P0 死配置修复，配置真实生效）
+              deny: DENY       # fail-closed 兜底（未分类违规 → 兜底原语）；可配置为其他拒绝类原语
+                               # （如 REQUIRE_APPROVAL）；不可为 ALLOW——resolve 校验回退 DENY（保证配置真实生效）
             flags:
-              pause: false     # 原语开关（CAGE feature-flag 借鉴 hf.md:83-85；默认关 → P3 回退 DENY）
+              pause: false     # 原语开关（feature-flag 式；默认关 → 该原语回退 DENY）
               narrow: false
               defer: false

package/docs/guardrails-hook.en.md

@@ -15,7 +15,7 @@ Execution order: pre-execute event chain (kernel) → ask resolution → difficu
 ## 1. Two-Phase Wiring
 
 - **pre-execute**: session-state pre-check (session deferred/paused → reject directly, see §2 DEFER/PAUSE) → kernel adjudication → ALLOW passes through (`next()`); non-ALLOW synchronously writes the refusal receipt (failure only warns, observer discipline, does not block adjudication) → returns `{kind:'deny'|'ask'}`;
-- **post-execute**: pass-through observer — always `next()`, never alters the result; only best-effort backfills the ask outcome (lookup + inference, write failure only warns);
+- **post-execute**: pass-through observer — always `next()`, never alters the result; only best-effort backfills the ask outcome (lookup + inference, write failure only warns). **Controlled exception (denial visibility, controlled correction)**: once the host's serviceAsk generic branches (rejected/cancelled/unavailable/no-agent) overwrite ask.reason, post short-circuits with a corrected agent-visible text for matched asks of this plugin — returns `{kind:'accept', content:[corrected text]}` (the host's accept+content replacement swaps only the display content, preserving isError:true and error.message); the short-circuit condition is strictly narrowed (only those 4 branches plus a matched pending ask of this plugin), backfill/correction failures degrade to `next()` (zero behavior regression); every other scenario stays `next()` (see §2);
 - **event order**: pre → execute → post → result; this hook never calls `ctx.emit` to tamper with the event stream; on the pre-rejection short path execute does not run, but the post observer is still invoked (the degraded-deny path of ask is backfilled the same way);
 - **teardown**: `dispose()` unsubscribes pre + post listeners in order (idempotent).
 
@@ -41,8 +41,8 @@ Adjudication order (category priority, first match wins):
 7. `soft` with confidence ≥ 0.70 → REQUIRE_APPROVAL;
 8. unclassified violations → fallback primitive (defaults.deny, default DENY; never ALLOW — fail-closed).
 
-- **Unified refusal message format**: `[governance:<primitive>] <reason>` (primitive ∈ ALLOW/DENY/REQUIRE_APPROVAL/DEFER/NARROW/PAUSE; aligned with the difficulty gate's `[task-difficulty-gate]` prefix style) — the model side can distinguish "task level unassessed" from "call level out of bounds". DENY/DEFER/NARROW/PAUSE all land as `{kind:'deny'}`; REQUIRE_APPROVAL → `{kind:'ask'}`.
-- **REQUIRE_APPROVAL ask behavior (explicit)**: pre synchronously writes `ask: {channel:'host-serviceAsk', initiated, requestId(=callId)}`; post best-effort backfills `outcome` (denied-no-approval / denied-no-agent / denied-rejected / denied-cancelled / unavailable / allowed-once). **Depends on the host approval channel (serviceAsk); no approval service / no agent → degraded deny** (behavior unchanged, record made explicit); allowed-once → allow.
+- **Unified refusal message format**: `[governance:<primitive>] <reason>` (primitive ∈ ALLOW/DENY/REQUIRE_APPROVAL/DEFER/NARROW/PAUSE; aligned with the difficulty gate's `[task-difficulty-gate]` prefix style) — the model side can distinguish "task level unassessed" from "call level out of bounds". DENY/DEFER/NARROW/PAUSE all land as `{kind:'deny'}`; REQUIRE_APPROVAL → `{kind:'ask'}`. **Matched-rule reference**: when ruleRefs is non-empty the reason appends「; rule reference: `<ruleId>` (preset `<presetId>`)」— carried by both the DENY short path and ask.reason (if the approval UI renders reason, the matched rules are visible before the user rejects; custom rules without preset attribution list only the rule id).
+- **REQUIRE_APPROVAL ask behavior (explicit)**: pre synchronously writes `ask: {channel:'host-serviceAsk', initiated, requestId(=callId)}` (and caches a decision snapshot — primitive/reason/ruleRefs — for zero-disk-read post correction); post best-effort backfills `outcome` (denied-no-approval / denied-no-agent / denied-rejected / denied-cancelled / unavailable / allowed-once). **Depends on the host approval channel (serviceAsk); no approval service / no agent → degraded deny** (behavior unchanged, record made explicit); allowed-once → allow. **Denial visibility (controlled exception)**: the host's serviceAsk overwrites ask.reason with tool-name-level generic text on 4 generic branches — rejected (`user rejected`) / cancelled (`was cancelled`) / unavailable (`no approval channel is available`) / no-agent (`no agent to route it through`) — e.g. `the user rejected tool "pwsh"` (no guardrail marker, no matched rules); the wiring post observer **short-circuits a controlled correction** for matched asks of this plugin: returns `{kind:'accept', content:[corrected text]}` whose text carries the `[governance:REQUIRE_APPROVAL approval-gate rejection (guardrail interception…)]` marker + matched rules (rule id + preset attribution) + violation message + receipt/checklist lookup paths (<root>/governance/refusals/… and presets/hook-rules/README.md), preserving isError and degrading to `next()` on failure (zero behavior regression); **denied-no-approval (no-approval-service degrade — the host keeps ask.reason, i.e. the guardrail-prefixed text) is not corrected** (no duplicate annotation). The short-circuit condition is strictly narrowed; the boundary of touching the "post always next()" discipline lives in §1/§7.
 - **DEFER/PAUSE file-state state machine (truly effective once flags are on)**: `flags.defer: true` (soft violation) → session suspended and deferred (state file `<root>/governance/state/<sessionId>.json`, window 30s, receipt carries `deferMeta`); `flags.pause: true` (pausable violation) → session paused (window 60s, receipt carries `pauseMeta`). While suspended/paused, same-session calls are uniformly denied with `[governance:DEFER|PAUSE]` (reason includes retry-after / pauseToken / until); **lazy expiry auto-recovers** (cleaned on read; no timer / no resume endpoint); flag-off collapses to DENY with no state side effect (distinguishable from "session deferred/paused").
 
 ## 3. Configuration Guide and Example Rules
@@ -142,6 +142,21 @@ The current guardrails provide in-process, single-machine, rule-table-driven cal
 - full RFC8785 (numeric normalization / per-character escaping) and true-signature evidence envelope (the sha256-chain simplified version is provided, see §4);
 - immutable storage (write-once class).
 
+### Engine boundaries and denial-visibility lookup paths
+
+**Engine boundaries (host dependency layer — not modifiable by the plugin)**:
+
+- The host's `serviceAsk` retention/concatenation of the denial reason — its rejected/cancelled/unavailable/no-agent branches overwrite `ask.reason` with tool-name-level generic text; the true root fix requires the host upstream to retain/concatenate reason (an npm overlay would be lost — not provided); the plugin compensates via the post controlled correction (see §2);
+- The host approval UI's rendering of reason (whether the approval card shows multi-line guardrail details) — host web implementation; the plugin only guarantees that the reason text (with the rule reference) reaches the UI via `approval.request`;
+- Per-rule view/edit on the WebUI「Governance Configuration」page — the page itself lives in the host's dsh-web; the plugin only exposes presetCatalog metadata; the current review surface is this repo's rule checklist (see ④ below).
+
+**Denial-visibility lookup paths** (traceable chain "visible text → audit detail → full rule list"):
+
+- ① Agent-reported text after a refusal (controlled-correction text): session-immediately-visible `[governance:REQUIRE_APPROVAL approval-gate rejection…]` + matched rules (rule id + preset attribution) + violation message + receipt path; the Agent can retry a compliant call following the violation message;
+- ② Approval-request reason (rule-reference delivery): reason tail「; rule reference: …」, delivered to the host UI with `approval.request`;
+- ③ Receipt details (manual/audit): `<root>/governance/refusals/<sessionId>/<receiptId>.json` (decision.reason + ruleRefs + attemptedParams + ask.outcome, hash-anchored) + `ledger-<sessionId>.jsonl` + the batch-level event stream (see §4/§5);
+- ④ Full rule list (proactive review): the「Per-rule review checklist」in `presets/hook-rules/README.md` (l1-sensitive 12 + l2-resource 6; rule id/preset/category/primitive/tools/match/message) + the preset JSON files.
+
 ## 8. Capability Boundaries & Trade-offs
 
 The call-level guardrails extend governance beyond the task level with a call-level line of defense while keeping determinism, auditability, zero added dependencies, and zero host modification. The summary below is grouped into **enhancement surface / capability boundaries / technical trade-offs** (implementation details in §1–§7).

package/docs/guardrails-hook.md

@@ -15,7 +15,7 @@
 ## 1. 双阶段接线
 
 - **pre-execute**：状态前置检查（会话延后/暂停中 → 直接拒绝，见 §2 DEFER/PAUSE）→ 内核裁决 → ALLOW 则透传（`next()`）；非 ALLOW 同步落盘拒绝收据（失败仅 warn，观察者纪律，不阻断裁决）→ 返回 `{kind:'deny'|'ask'}`；
-- **post-execute**：pass-through 观察者——恒 `next()`，不篡改结果；仅尽力补记 ask outcome（查表推断，写失败仅 warn）；
+- **post-execute**：pass-through 观察者——恒 `next()`，不篡改结果；仅尽力补记 ask outcome（查表推断，写失败仅 warn）。**受控例外（拒绝可见性，受控补正）**：宿主 serviceAsk 泛化分支（rejected/cancelled/unavailable/no-agent）覆盖 ask.reason 后，post 对本插件 ask 命中分支**短路补正** Agent 可见文本——返回 `{kind:'accept', content:[补正文本]}`（宿主 accept+content 替换仅改展示 content、保 isError:true 与 error.message）；短路条件严格收窄（仅该 4 分支 + 本插件 pendingAsk 命中），补记/补正失败降级恒 `next()`（零行为回归）；其余一切场景恒 `next()`（详见 §2）；
 - **事件序**：pre → execute → post → result；本 hook 不调用 `ctx.emit` 篡改事件流；pre 拒绝短路径下 execute 不执行，post 观察者仍被调用（ask 降级 deny 路径同样补记）；
 - **卸载**：`dispose()` 依次卸载 pre + post listener（幂等）。
 
@@ -41,8 +41,8 @@
 7. `soft` 置信 ≥ 0.70 → REQUIRE_APPROVAL；
 8. 未分类违规 → 兜底原语（defaults.deny，缺省 DENY；绝不 ALLOW——fail-closed）。
 
-- **统一拒绝消息格式**：`[governance:<primitive>] <reason>`（primitive ∈ ALLOW/DENY/REQUIRE_APPROVAL/DEFER/NARROW/PAUSE；对齐难度门禁 `[task-difficulty-gate]` 前缀风格）——模型侧可区分「任务级未评估」vs「调用级越界」。DENY/DEFER/NARROW/PAUSE 统一以 `{kind:'deny'}` 落地；REQUIRE_APPROVAL → `{kind:'ask'}`。
-- **REQUIRE_APPROVAL ask 行为（显式化）**：pre 同步落盘 `ask: {channel:'host-serviceAsk', initiated, requestId(=callId)}`；post 尽力补记 `outcome`（denied-no-approval / denied-no-agent / denied-rejected / denied-cancelled / unavailable / allowed-once）。**依赖宿主 approval 通道（serviceAsk），无审批服务 / 无 agent = 降级 deny**（行为不变，记录显式化）；allowed-once → allow。
+- **统一拒绝消息格式**：`[governance:<primitive>] <reason>`（primitive ∈ ALLOW/DENY/REQUIRE_APPROVAL/DEFER/NARROW/PAUSE；对齐难度门禁 `[task-difficulty-gate]` 前缀风格）——模型侧可区分「任务级未评估」vs「调用级越界」。DENY/DEFER/NARROW/PAUSE 统一以 `{kind:'deny'}` 落地；REQUIRE_APPROVAL → `{kind:'ask'}`。**命中规则引用**：ruleRefs 非空时 reason 尾部追加「；规则引用：`<ruleId>`（preset `<presetId>`）」——DENY 短路径与 ask.reason 均携带（审批 UI 若渲染 reason，用户拒绝前即可见命中规则；无 preset 归属的自定义规则仅列 rule id）。
+- **REQUIRE_APPROVAL ask 行为（显式化）**：pre 同步落盘 `ask: {channel:'host-serviceAsk', initiated, requestId(=callId)}`（登记时顺带缓存 decision 快照：primitive/reason/ruleRefs——post 补正零盘读）；post 尽力补记 `outcome`（denied-no-approval / denied-no-agent / denied-rejected / denied-cancelled / unavailable / allowed-once）。**依赖宿主 approval 通道（serviceAsk），无审批服务 / 无 agent = 降级 deny**（行为不变，记录显式化）；allowed-once → allow。**拒绝可见性（受控例外）**：宿主 serviceAsk 在 4 个泛化分支——rejected（`user rejected`）/ cancelled（`was cancelled`）/ unavailable（`no approval channel is available`）/ no-agent（`no agent to route it through`）——会把 ask.reason 覆盖为「工具名级」泛化文本（如 `the user rejected tool "pwsh"`，无护栏标识、无命中规则）；wiring post 观察者对本插件 ask 命中分支做**受控补正**：短路返回 `{kind:'accept', content:[补正文本]}`——补正文本含 `[governance:REQUIRE_APPROVAL 人工闸拒绝（护栏拦截…）]` 护栏标注 + 命中规则（rule id + preset 归属）+ 违规 message + 收据/清单查阅路径（<root>/governance/refusals/… 与 presets/hook-rules/README.md），保 isError、失败降级恒 `next()`（零行为回归）；**denied-no-approval（无审批服务降级，宿主保留 ask.reason 即护栏前缀正文）不补正**（不重复标注）。短路条件严格收窄，触碰「post 恒 next」纪律的边界见 §1/§7。
 - **DEFER/PAUSE 文件态状态机（flag 开启后真实生效）**：`flags.defer: true`（soft 违规）→ 会话挂起延后（状态文件 `<root>/governance/state/<sessionId>.json`，窗口 30s，收据含 `deferMeta`）；`flags.pause: true`（pausable 违规）→ 会话暂停（窗口 60s，收据含 `pauseMeta`）。挂起/暂停期间同会话调用统一 `[governance:DEFER|PAUSE]` deny（reason 含 retry-after / pauseToken / until），**惰性过期自动恢复**（读时清理，无定时器 / 无 resume 端点）；flag-off 折叠 DENY 无状态副作用（与「会话延后/暂停中」可区分）。
 
 ## 3. 配置指南与示例规则
@@ -142,6 +142,21 @@ governance:
 - 完整 RFC8785（数字规范化 / 逐字符转义）与真签名证据信封（sha256 链简版已提供，见 §4）；
 - 不可变存储（write-once 类）。
 
+### 引擎边界与拒绝可见性查阅路径
+
+**引擎边界（宿主依赖层，插件不可改）**：
+
+- 宿主 `serviceAsk` 对拒绝 reason 的保留/拼接——rejected/cancelled/unavailable/no-agent 四分支把 `ask.reason` 覆盖为「工具名级」泛化文本；真根修需宿主上游保留/拼接 reason（npm 覆盖即丢，不提供），插件侧以 post 受控补正兜底（见 §2）；
+- 宿主审批 UI 对 reason 的渲染形态（审批卡片是否展示多行护栏明细）——宿主 Web 实现；插件只保证 reason 文本（含规则引用）随 `approval.request` 送达；
+- WebUI「治理配置」页逐条规则查看/编辑——页面本体在宿主 dsh-web；插件只提供 presetCatalog 元数据，当前审阅面 = 本仓库规则清单（见下 ④）。
+
+**拒绝可见性查阅路径**（「可见文本 → 审计明细 → 全量清单」可追溯链）：
+
+- ① 被拒后 Agent 汇报文本（受控补正文本）：会话内即时可见 `[governance:REQUIRE_APPROVAL 人工闸拒绝…]` + 命中规则（rule id + preset 归属）+ 违规 message + 收据路径，Agent 可按违规 message 修正参数后重发合规调用；
+- ② 审批请求 reason（规则引用送达）：reason 尾部「；规则引用：…」，随 approval.request 送达宿主 UI；
+- ③ 收据明细（人工/审计）：`<root>/governance/refusals/<sessionId>/<receiptId>.json`（decision.reason + ruleRefs + attemptedParams + ask.outcome，哈希锚定）+ `ledger-<sessionId>.jsonl` + 批级事件流（见 §4/§5）；
+- ④ 全量规则清单（主动审阅）：`presets/hook-rules/README.md`「逐条规则审阅清单」（l1-sensitive 12 + l2-resource 6，rule id/preset/category/原语/tools/match/message）+ 各 preset JSON。
+
 ## 8. 能力边界与取舍
 
 调用级护栏把治理能力从任务级扩展出调用级一道防线，同时保持确定性、可审计、零新增依赖与零宿主改造。以下按**增强面 / 能力边界 / 技术取舍**三组小结（实现细节见 §1–§7）。

package/lib/acps/certs.js

@@ -15,7 +15,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-// 文件 certs：ACPs mTLS 证书材料（lib/acps 域，P1 lane exec-acps-server）
+// 文件 certs：ACPs mTLS 证书材料（lib/acps 域）
 // 契约：CAI 自签（node:crypto 自签 X.509，零新依赖）；文件三路径（cert/key/ca 三路径
 //       config 可配，默认 acps 数据目录）；TLS 语义对齐参考实现
 //       registry-server/app/main_mtls.py:14-30（cert/key/ca 三件套 + CERT_REQUIRED + TLSv1_3）。

package/lib/acps/server.js

@@ -15,7 +15,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-// 文件 server：ACPs 对外 mTLS 服务端点（lib/acps 域，P1 lane exec-acps-server）
+// 文件 server：ACPs 对外 mTLS 服务端点（lib/acps 域）
 // 契约：
 //   - 独立 HTTPS 监听器（node:https + node:tls，零新依赖），默认端口 9443、绑定 127.0.0.1（config 可配）；
 //   - TLS：minVersion TLSv1.3 + requestCert + rejectUnauthorized（=CERT_REQUIRED + TLSv1_3 语义，

package/lib/aip/agent-descriptor.js

@@ -21,7 +21,7 @@ along with this program. If not, see <https://www.gnu.org/licenses/>.
 // ⚠ 2026-08 校准（覆盖旧 14+8 口径）：字段集以 ACS（Agent Capability Specification）原文为准——
 //   registry-server/app/agent/acsSchema.json（JSON Schema 全文）为逐字字段来源；
 //   旧「14+8 兼容映射层」（toLegacyDescriptor / toLegacySkill + ALL_TOOLS / LAYER_CAPABILITIES）
-//   已移除（P2-06）：ACPs 兼容路径中无调用——ACPs 描述直接消费 buildAgentDescriptor 的 ACS 格式
+//   已移除：ACPs 兼容路径中无调用——ACPs 描述直接消费 buildAgentDescriptor 的 ACS 格式
 //   （server.js:37,136 装配），描述以 ACS 格式为准。
 // 派生值标记：固定值 = 本文件推导；预留 = 后续填充。
 // 仅用内建能力，零新增依赖（红线：不改 node_modules）。

package/lib/aip/identity.js

@@ -17,7 +17,7 @@ along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 // 文件 identity：国标 P2/P3 身份体系（AIC 身份码 + CAI 身份证书）
 // -----------------------------------------------------------------------------
-// 校准基准（plan/spec.md §3.4/§3.5，[参考] = ACPs-community v2.1.0 原文）：
+// 校准基准（§3.4/§3.5；[参考] = ACPs-community v2.1.0 原文）：
 //   P2 身份码 AIC：10 级编码（前缀 1.2.156.3088 + 版本/ARSP/供应商/本体/实体 + 校验码），
 //     CRC-16/CCITT-FALSE（poly=0x1021, init=0xFFFF, refin/refout=false, xorout=0x0000）+
 //     ARSP 盐值（>=2 字节）+ Base36 固定 4 位校验码（ACPs-spec-AIC-v02.01 §4）。

package/lib/api.js

@@ -20,10 +20,10 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import * as mailbox from './comms/mailbox.js';
 import { createStreamHub } from './panel/stream.js';
-// P1 批 R-07 排除项（承接归 panel 批）：事件读端字面量收敛——EVT 常量源 lib/state/event-types.js（P2-07 单点）
+// 事件读端字面量收敛：EVT 常量单源 lib/state/event-types.js
 import * as EVT from './state/event-types.js';
-// WebUI 治理配置写通道（webui-config-build-20260903）：/config 端点 trusted 判定（自复刻宿主 /api
-//   护栏语义，conn:184-198 未导出故复刻——插件 exact 路由不经宿主护栏，写端点须自理，见 config-trust.js）
+// WebUI 治理配置写通道：/config 端点 trusted 判定（自复刻宿主 /api
+//   护栏语义，宿主未导出故复刻——插件 exact 路由不经宿主护栏，写端点须自理，见 config-trust.js）
 import { isTrustedConfigRequest } from './webui/config-trust.js';
 
 function sendJson(res, status, data) {
@@ -41,9 +41,9 @@ export function createApi(ctx, deps) {
   const disposers = [];
   const register = (route) => disposers.push(ctx.webServer.register(route));
 
-  // R3 SSE hub（设计 §3.3.3）：随 webServer 挂载（ADR-4：无独立配置键；降级回轮询即运行时自适配开关）。
-  // 装配点（index.js 层，exec-a 批②）预留时经 deps.panelStream 注入复用（含 topic 触发源 attachTopic 接线）；
-  // 缺省自建（fs.watch 单通道先行交付——契约移交点语义），自建者负责 dispose。
+  // SSE hub：随 webServer 挂载（无独立配置键；降级回轮询即运行时自适配开关）。
+  // 装配点（index.js 层）预留时经 deps.panelStream 注入复用（含 topic 触发源 attachTopic 接线）；
+  // 缺省自建（fs.watch 单通道先行交付），自建者负责 dispose。
   const panelStream = deps.panelStream || createStreamHub({ root, logger: ctx.logger });
   if (!deps.panelStream) disposers.push(() => { try { panelStream.dispose(); } catch {} });
 
@@ -112,7 +112,7 @@ export function createApi(ctx, deps) {
           laneAttempts,
           upgrades,
           lanesGate: Object.fromEntries(Object.keys(b.lanes).map((l) => [l, store.gateStatus(session, batchId, l)])),
-          // P6 接线（exec-format-wire）：装配注入 aipFormat 时附 ACPs Session 投影（纯函数，不改存储；缺省不附 → 既有响应不变）
+          // 装配注入 aipFormat 时附 ACPs Session 投影（纯函数，不改存储；缺省不附 → 既有响应不变）
           ...(aipFormat ? { aipSession: aipFormat.toAipSession(b) } : {}),
         });
       } catch (e) { sendJson(res, 500, { error: String(e.message) }); }
@@ -127,7 +127,7 @@ export function createApi(ctx, deps) {
         const { batchId, box, lane, session } = q(req.url);
         if (!batchId || !box) return sendJson(res, 400, { error: 'batchId+box required' });
         if (!session) return sendJson(res, 400, { error: 'session required' });
-        // P2-08：box 枚举校验——非法 box 返回 400（含枚举提示）而非透传进 mailbox.readUnacked 抛错兜成 500
+        // box 枚举校验——非法 box 返回 400（含枚举提示）而非透传进 mailbox.readUnacked 抛错兜成 500
         const BOXES = ['inbox', 'outbox', 'broadcast'];
         if (!BOXES.includes(box)) {
           return sendJson(res, 400, { error: 'invalid box: ' + box + ' (allowed: ' + BOXES.join(' | ') + ')' });
@@ -136,7 +136,7 @@ export function createApi(ctx, deps) {
         if (box === 'outbox' && !lane) return sendJson(res, 400, { error: 'lane required for outbox' });
         const b = box === 'outbox' ? { type: 'outbox', lane } : { type: box };
         const items = mailbox.readUnacked(join(root, 'sessions', session, 'mailbox', batchId), b);
-        // P6 接线（exec-format-wire）：装配注入 aipFormat 时逐条附 ACPs Message 投影（纯函数投影，不改 mailbox 存储与 ack 语义）
+        // 装配注入 aipFormat 时逐条附 ACPs Message 投影（纯函数投影，不改 mailbox 存储与 ack 语义）
         sendJson(res, 200, aipFormat ? { items: items.map((it) => ({ ...it, aip: aipFormat.toAipMessage(it) })) } : { items });
       } catch (e) { sendJson(res, 500, { error: String(e.message) }); }
     },
@@ -159,7 +159,7 @@ export function createApi(ctx, deps) {
     },
   });
 
-  // 国标 AIP 工具列表同步（方案 A：只读 API 端点）：catalog 非空（缺省默认开启）时注册 /tools；
+  // 国标 AIP 工具列表同步（只读 API 端点）：catalog 非空（缺省默认开启）时注册 /tools；
   // 仅显式 aip.enabled=false 时 catalog 为 null，不注册该路由（保持既有 6 路由契约）。
   // catalog 由 register.js 经 readCapability 默认合并口径提供——本条件与 enabled 联动，此处零逻辑改动。
   if (catalog) {
@@ -176,7 +176,7 @@ export function createApi(ctx, deps) {
     });
   }
 
-  // P4 ACS 智能体描述目录：enabled=true 时 agentCatalog 非空，注册 /agents；
+  // 智能体描述目录：enabled=true 时 agentCatalog 非空，注册 /agents；
   // 端点输出 ACS 字段集（AgentCapabilitySpec，逐字字段见 lib/aip/agent-descriptor.js）；只读、无参。
   // aip.enabled=false（显式关闭——aip 出厂默认开，readCapability 缺省合并 {enabled:true}）时 agentCatalog 为 null，不注册该路由（既有路由契约不变）。
   if (agentCatalog) {
@@ -191,7 +191,7 @@ export function createApi(ctx, deps) {
       },
     });
   }
-  // 国标 P5 发现服务（ADP 语义）：discovery 服务实例注入时注册
+  // 发现服务（ADP 语义）：discovery 服务实例注入时注册
   //   POST /api/dsh-punky-swarm/discover — 统一发现查询（DiscoveryRequest → DiscoveryResponse）
   //   GET  /.well-known/aip          — 发现服务预置信息（地址/协议版本/能力概要）
   if (discovery) {
@@ -220,11 +220,11 @@ export function createApi(ctx, deps) {
     });
   }
 
-  // WebUI 治理配置写通道（webui-config-build-20260903，设计 §1.1/§1.2，落点 = discover 段与 stream 段之间）：
+  // WebUI 治理配置写通道（路由落点 = discover 段与 stream 段之间）：
   //   GET + POST /api/dsh-punky-swarm/config —— 配置页页载取数 / 受控字段集保存（写 <root>/config/runtime.json）。
-  //   条件注册仿 discovery/agentCatalog（上方 :162-190 注入形态）：deps.configEndpoints.runtimeConfig
+  //   条件注册仿 discovery/agentCatalog（上方注入形态）：deps.configEndpoints.runtimeConfig
   //   注入时注册；未注入不注册 → 既有 7 路由/9 路由计数测试零回归（不改既有注册面，disposer 统一回收）。
-  //   trusted 判定（GET/POST 共用，§1.3）：Host loopback/trustedHosts + sec-fetch-site≠cross-site + Origin 同源
+  //   trusted 判定（GET/POST 共用）：Host loopback/trustedHosts + sec-fetch-site≠cross-site + Origin 同源
   //   （isTrustedConfigRequest，lib/webui/config-trust.js；trustedHosts 出厂 [] → loopback-only）。
   //   写逻辑全在 service（lib/webui/runtime-config.js）：白名单预检 400 → 读-改-写 → validateOverlay
   //   兜底 500 → tmp+rename 原子写；GET 取数 overlay（磁盘原样）/applied（装配侧解析快照）/presets（注册目录）。
@@ -235,7 +235,7 @@ export function createApi(ctx, deps) {
       kind: 'exact',
       path: '/api/dsh-punky-swarm/config',
       handler(req, res) {
-        // trusted 护栏前置（GET/POST 共用；护栏语义非鉴权层、防 DNS-rebinding/跨站——§1.2）
+        // trusted 护栏前置（GET/POST 共用；护栏语义非鉴权层、防 DNS-rebinding/跨站）
         if (!isTrustedConfigRequest(req, trustedHosts)) {
           const body = req.method === 'POST' ? { ok: false, error: 'forbidden' } : { error: 'forbidden' };
           return sendJson(res, 403, body);
@@ -246,7 +246,7 @@ export function createApi(ctx, deps) {
             const gov = overlay && typeof overlay === 'object' && !Array.isArray(overlay)
               && overlay.governance && typeof overlay.governance === 'object' && !Array.isArray(overlay.governance)
               ? overlay.governance : null;
-            // watch 段取数（longrun-panel-config-20260905）：overlayWatch = 磁盘 capabilities.watch 段原样
+            // watch 段取数：overlayWatch = 磁盘 capabilities.watch 段原样
             //   （无 = null）；applied.watch = 装配侧解析生效快照（watchInstalledCfg，经 appliedWatch getter——
             //   未注入时省略该键，旧 harness/旧客户端零感知）。既有 overlay=governance 语义不动。
             const caps = overlay && typeof overlay === 'object' && !Array.isArray(overlay)
@@ -276,8 +276,8 @@ export function createApi(ctx, deps) {
           }
           return bodyPromise.then((payload) => {
             try {
-              // POST 按 body 键存在性分派（longrun-panel-config-20260905）：含 capabilities 段 → writeWatch
-              //   （单保存合并 governance + capabilities.watch 双段同 body，Leader 裁决 1——writeWatch 内部
+              // POST 按 body 键存在性分派：含 capabilities 段 → writeWatch
+              //   （单保存合并 governance + capabilities.watch 双段同 body——writeWatch 内部
               //   同时处理可选 governance 段，分节校验 + 单次原子写）；仅 governance（旧客户端/既有测试契约）
               //   → writeGovernance 原路径（错误形态与路由零变化）。
               const hasCaps = payload && typeof payload === 'object' && !Array.isArray(payload) && 'capabilities' in payload;
@@ -292,7 +292,7 @@ export function createApi(ctx, deps) {
               }
               return sendJson(res, 200, { ok: true, written: out.written, ts: new Date().toISOString() });
             } catch (e) {
-              // 读-改-写 IO 异常（坏 base JSON / rename 失败等）→ 500 不回写（设计 §1.5「不应发生」面）
+              // 读-改-写 IO 异常（坏 base JSON / rename 失败等）→ 500 不落盘（「不应发生」面）
               return sendJson(res, 500, { ok: false, error: String(e?.message ?? e) });
             }
           }).catch((e) => sendJson(res, 400, { ok: false, error: 'invalid-json: ' + String(e?.message ?? e) }));
@@ -302,10 +302,10 @@ export function createApi(ctx, deps) {
     });
   }
 
-  // R3 SSE 端点（设计 §3.3.3，纯新增路由——既有 /api 路由一字不动）：
+  // SSE 端点（纯新增路由——既有 /api 路由一字不动）：
   //   GET /api/dsh-punky-swarm/stream?session=<sid>[&batchId=<bid>]
   //   SSE 帧协议：event: batch|mailbox|heartbeat + data:<JSON>；注释心跳帧每 10s（hub 内维护）。
-  //   推送只发轻量摘要 {sessionId,batchId,eventCount,updatedAt}，客户端回拉既有只读 API 取全量（ADR-5）。
+  //   推送只发轻量摘要 {sessionId,batchId,eventCount,updatedAt}，客户端回拉既有只读 API 取全量。
   register({
     kind: 'exact',
     path: '/api/dsh-punky-swarm/stream',

package/lib/artifact-types.js

@@ -15,7 +15,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-// 通用产物类型注册表（2026-08-19，Tier3 增量）
+// 通用产物类型注册表
 // 定位：通用任务治理模式——登记产物类型 → 层/目录前缀的约定，供校验与查询；
 // 不绑定任何团队模板（jiufeng 四件套只是使用者，产物内部格式归模板层）。
 // 三层目录约定：plan/（任务层）、exec/（执行层）、audit/（审计层），与 wave-plan 路径契约一致。

package/lib/assembly/schema.js

@@ -43,11 +43,11 @@ export const CAPABILITY_REGISTRY = [
   { key: 'worktree', path: ['capabilities', 'worktree'], default: { enabled: true, mergeAgent: { enabled: false, model: null, timeoutMs: 600000 } }, consumers: ['tools/lane-tools.js 三工具注册'] },
   { key: 'budget', path: ['capabilities', 'budget'], default: { enabled: true, maxChainHops: 4, maxChainRoundTrips: 2 }, consumers: ['comms/budget.js + mailbox-tools.js 发送检查'] },
   { key: 'trajectory', path: ['capabilities', 'trajectory'], default: TRAJECTORY_DEFAULTS, consumers: ['index.js 桥接订阅'] },
-  // logs 键（E3 增强，P1-01）：日志导出工具注册开关——默认关（与 cordis.patch.yml 显式 logs.enabled:true 相合）；
+  // logs 键：日志导出工具注册开关——默认关（与 cordis.patch.yml 显式 logs.enabled:true 相合）；
   //   消费点经 readCapability(config,'logs') 缺省读取，显式 enabled:false 可关。
   { key: 'logs', path: ['capabilities', 'logs'], default: { enabled: false }, consumers: ['tools/log-tools.js log_export 注册'] },
-  // topic 键（P1-03）：comms/topic.js 预留模块开关——默认关；接线（trajectory 桥广播改经本模块等）归操作面板批次，本批不实施。
-  { key: 'topic', path: ['capabilities', 'topic'], default: { enabled: false }, consumers: ['comms/topic.js（预留，接线归操作面板批次）'] },
+  // topic 键：comms/topic.js 预留模块开关——默认关；接线（trajectory 桥广播改经本模块等）预留。
+  { key: 'topic', path: ['capabilities', 'topic'], default: { enabled: false }, consumers: ['comms/topic.js（预留）'] },
 ];
 
 // ── 互斥表（预留空表：当前能力两两可叠加；未来互斥能力登记于此）──
@@ -64,8 +64,8 @@ export const BLIND_REVIEW_ROLES = ['audit-panelist', 'audit-aggregate', 'audit-c
 export const BLIND_REVIEW_TEMPLATE_KEYS = ['bundle', 'panelist', 'aggregate', 'critic', 'checklist', 'config'];
 
 // ── 内部工具 ──
-// R1 热更新（lib/hot/config-watch.js）导出复用本函数做 runtime 覆盖层 deepMerge——
-// 禁止复制散落实现（复制即漂移源，设计 §5.3 风险点 1）；readCapability 缺省合并与本函数同源。
+// 热更新（lib/hot/config-watch.js）导出复用本函数做 runtime 覆盖层 deepMerge——
+// 禁止复制散落实现（复制即漂移源）；readCapability 缺省合并与本函数同源。
 export function deepMerge(base, override) {
   if (override === undefined || override === null) return base;
   if (typeof base !== 'object' || base === null || typeof override !== 'object' || override === null) return override;

package/lib/assembly.js

@@ -15,7 +15,7 @@ You should have received a copy of the GNU Affero General Public License
 along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-// 可插拔装配数据（设计 §12.1/§14.2/§15.3 N7）：team → layer → role → skills
+// 可插拔装配数据：team → layer → role → skills
 // 引擎只认 "role 契约 + skill 前缀" 通用格式，不感知 team；非 jiufeng 团队 = 换装配（外部路径 config.assembly 或自定义 resolveAssembly）
 export const DEFAULT_ASSEMBLY = {
   team: 'jiufeng',

package/lib/bridge/dispatch-register.js

@@ -15,17 +15,17 @@ You should have received a copy of the GNU Affero General Public License
 along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
-// bridge/dispatch-register.js —— D-1 方案 B 写侧登记点（m5a-d1-20260902 批次，装配注入 resolveBatchContext 兜底登记）
-// 背景：M5-a C2 归属读侧骨架（lib/index.js:414-430 dispatchIndex，从批次事件 member.dispatch 幂等重建）已就位，
-//   但写侧无真实调用方（audit m5a-acceptance §7 D-1 FAIL：trajectory.recordDispatch 全 lib 无生产调用方）。
-//   本模块 = 用户裁决的方案 B（audit §7.4 + m5a-plan §8-① 标注 b）：装配层 post-execute 观察 Manager 派发
-//   worker 的工具调用（subagent/subagent_fork/send_message 等）→ 提取返回的 childId/agentId + resolveBatchContext(exec)
-//   得当前批/lane → 写 member.dispatch 事件（store.appendEvent，与读侧骨架对接零改动生效——启动重建 + miss 惰性重建
-//   均自动感知）；未取到批上下文（非 Manager 派发场景）→ 不登记（保持 T16 无登记静默降级语义）。
-// 零宿主改造：仅订阅宿主既有 tools/post-execute waterfall（pass-through 恒 next()，先例 evidence.js:232-247）；
-//   swarm 自身工具（member_status 等）同样流经该 waterfall（evidence CONTROL_PLANE_TOOLS 佐证）→
-//   兜底解析 = 观察同会话 member_status(status=running) 的派发意图（0g 时序：先置 running 再派发 worker）。
-// 语义红线：漏计不误暂停（T16 安全侧）——解析不出批上下文宁可跳过；不引入任何批级状态迁移。
+// bridge/dispatch-register.js —— 派发登记点（dispatch registration）：装配层观察派发工具，把
+//   「worker 会话 → { sessionId, batchId, lane }」写为 member.dispatch 批次事件。
+// 背景：归属读侧骨架（dispatchIndex，从批次事件 member.dispatch 幂等重建）依赖写侧登记；
+//   本模块经装配层 post-execute 观察 Manager 派发（member_status(status=running) 意图）
+//   → resolveBatchContext 得当前批/lane → store.appendEvent 写 member.dispatch
+//   （与读侧骨架对接零改动生效：启动重建 + miss 惰性重建，幂等）；
+//   未取到批上下文（非 Manager 派发场景）→ 不登记（无登记静默降级语义）。
+// 零宿主改造：仅订阅宿主既有 tools/post-execute waterfall（pass-through 恒 next()）；
+//   swarm 自身工具（member_status 等）同样流经该 waterfall → 兜底解析 = 观察同会话
+//   member_status(status=running) 的派发意图（时序：先置 running 再派发 worker）。
+// 语义红线：漏计不误暂停（安全侧）——解析不出批上下文宁可跳过；不引入任何批级状态迁移。
 import { EVT_MEMBER_DISPATCH } from '../state/event-types.js';
 import { sessionOf } from '../tools/shared.js'; // 会话解析与 swarm 工具同源（args.session ?? exec.agent.session.id）
 
@@ -63,12 +63,12 @@ export function extractWorkerSessionId(exec, result) {
   return m ? m[1] : null;
 }
 
-// D-1 方案 B 装配层登记点（对齐 mountVerify/installGovernanceHook 模式）：
+// 装配层登记点（对齐 mountVerify/installGovernanceHook 模式）：
 //   订阅 ctx.on('tools/post-execute')——识别派发类工具 → 提取 workerSessionId → resolveBatchContext(exec)
 //   （deps 显式注入优先；缺省 = 同会话 member_status(running) 派发意图兜底）→ 命中批上下文则 appendEvent
-//   member.dispatch {lane, workerSessionId}（读侧骨架零改动生效）；未命中 → 不登记（T16）。
+//   member.dispatch {lane, workerSessionId}（读侧骨架零改动生效）；未命中 → 不登记。
 //   幂等守卫：dispatchIndex.has(workerSessionId) 已映射 → 跳过（防 send_message 重复唤醒重复登记）。
-//   观察者纪律：任一失败仅 warn，恒 return next()（不阻断、不抛错——evidence.js:242-244 同款）。
+//   观察者纪律：任一失败仅 warn，恒 return next()（不阻断、不抛错）。
 // 返回 { installed, dispose, count, mapping }；ctx.on 缺失 → inert 静默降级（宿主能力缺失不炸）。
 export function installDispatchRegistration(ctx, deps = {}) {
   const { store, dispatchIndex, logger, resolveBatchContext, tools = DEFAULT_DISPATCH_TOOLS } = deps;
@@ -107,12 +107,12 @@ export function installDispatchRegistration(ctx, deps = {}) {
       // ② 非派发类工具 → 不登记（透传）
       if (!toolSet.has(exec.name)) return next();
       const workerSessionId = extractWorkerSessionId(exec, result);
-      if (!workerSessionId) return next(); // 无持久 worker 会话（background/foreground/失败）→ T16 不登记
+      if (!workerSessionId) return next(); // 无持久 worker 会话（background/foreground/失败）→ 不登记
       // ③ resolveBatchContext(exec)：显式注入优先，缺省 = 同会话派发意图兜底（装配注入 resolveBatchContext 兜底）
       const hit = typeof resolveBatchContext === 'function'
         ? resolveBatchContext(exec, { workerSessionId, result })
         : (intentBySession.get(caller) ?? null);
-      if (!hit || !hit.sessionId || !hit.batchId || !hit.lane) return next(); // 未取到批上下文 → T16 不登记
+      if (!hit || !hit.sessionId || !hit.batchId || !hit.lane) return next(); // 未取到批上下文 → 不登记
       if (register(hit.sessionId, hit.batchId, hit.lane, workerSessionId)) {
         intentBySession.delete(caller); // 消费意图（一次 running → 一次派发登记）
       }