[Permissions] Author three-part approval guidance and explicitly apply templates

.agents/skills/verify-deepseekbot/features/approval-templates.md

@@ -5,6 +5,7 @@ A Bot inherits the optional global default, selects one complete shared template
 ## Sub-features
 
 - `library`: Bot settings → Auto approval → Global default template (DSH Select), existing template library and Reviewer model. No global default means inherited review is off. Read failures remain errors.
+- `editor`: New template requires Blank or one selected source; edit independent Always ask/Always allow rows in the same grouped card list as External identities/connectors (outer top/bottom corners, straight middle joins), plus free text; save alone or apply to a named Bot. Copy a custom or built-in template independently; shared-original editing lists actual users including global inheritors. Read back full content and selection through CLI.
 - `cli`: `approval-template list --bot <bot>`, `approval-template-global-set <name|off>`, `approval-template-set <bot> <inherit|name|off>`; library create/edit commands retain existing Markdown contents.
 - `select`: Channel settings → Auto approval, or composer Workspace Grants panel → Auto approval, uses the same DSH Select. Inheritance shows its effective global source. Specific selection replaces global; Off retains deterministic rules.
 - `mobile`: Bot profile → Settings → Permissions → Workspace grants → Auto approval template, inside the existing iOS sheet / Android `ModalBottomSheet`. Inherit global shows the resolved global template (or Off); selecting Off then Inherit global writes null then @global through the same Host owner. Legacy Hosts without a global-selection field retain their supported choices.
@@ -33,7 +34,7 @@ Use the shared device QA lane and T3 device tools. The same synthetic Bot and is
 ## Gotchas
 
 - `/tmp` may already be writable; an ordinary file write there need not reach an approval gate.
-- Three-part editing, card-rule table and confirmed bulk deletion fallback are separate issues; this journey does not qualify them.
+- Card-rule table and confirmed bulk deletion fallback remain separate issues. For the editor, verify legacy Markdown survives conversion and an edit during a Review changes only the next captured version.
 - Browser screenshots establish Web behavior only. Preserve failed drives and observe before retrying.
 
 ## Human result retention (#4211)

changes/4244-template-guidance-editor.md

@@ -0,0 +1,11 @@
+---
+section: Changed
+---
+
+## en
+
+- Added explicit blank or selected-source template creation, independent copies, three-part Reviewer guidance, and separate save/apply choices; shared-original edits disclose the Bots using them, and Always ask/Always allow use the same grouped card list as external identities and connectors ([#4244](https://github.com/BotHarness/DeepSeekBot/issues/4244)).
+
+## zh
+
+- 新增明确选择空白或来源模板创建独立副本、三部分 Reviewer 指导及仅保存／保存并应用选项；编辑共享原件时显示使用它的 Bot；Always ask／Always allow 使用与外部身份及连接器一致的分组卡片列表（[#4244](https://github.com/BotHarness/DeepSeekBot/issues/4244)）。

docs/adr/0342-bot-approval-selects-one-template-and-keeps-deterministic-authorization-separate.md

@@ -29,3 +29,7 @@ The existing application-defined approval owner remains responsible for decision
 This amends ADR-0207's template selection, Markdown-only policy shape, three Reviewer outcomes and rejection circuit breaker as target design, not retroactive runtime fact. ADR-0249 continues to govern explicit management authorization. The existing issue bodies are not rewritten by this record.
 
 Rejected alternatives were global-plus-Bot layering (ambiguous effective policy), applying new defaults to old disabled Bots (implicit opt-in), autonomous model rejection (removes the Human's decision on unapproved requests), hidden copies/application (unclear scope), and refusing deletion until every reference is removed (unnecessary repeated work). The selected design makes defaults dynamic and deletion easier, at the cost of a carefully disclosed bulk change and immutable policy snapshots for already-started Reviews.
+
+## File compatibility for #4244
+
+Three-part editing keeps the existing template-file owner and 32 KiB bounded reader. A saved structured template uses the exact marker `<!-- botharness:approval-guidance:v1 -->`, a newline, then JSON containing `alwaysAsk` and `alwaysAllow` string arrays and `freeText`. This is a versioned content representation inside the existing file, not a SQLite migration. Legacy Markdown without that marker maps in full to free text with empty row arrays; headings are not parsed into rules or rewritten. Invalid marked content is unavailable, so a Review falls back to the Human. The Review content hash covers the complete saved representation; decoding for Reviewer assembly uses only that captured text. Copies contain content only. Global defaults and built-ins are unchanged.

docs/architecture/bot-approval-policy.md

@@ -110,6 +110,8 @@ Future delivery must demonstrate inherited versus specific/Off behavior, Reviewe
 
 Performance assessment: this change edits documentation only, introduces no dependency and changes no runtime hot path, so no runtime benchmark is warranted. Future E2/E3 work must separately budget added admission work and model calls, prove deterministic hits make no Reviewer call, and verify the affected real journey under the repository's performance policy.
 
+The #4244 editor retains the template-file owner and 32 KiB bounded reads. ADR-0342 records the v1 content representation; legacy Markdown maps intact to free text. Copies contain only content. Save and apply are separate choices, shared-original editing shows global inheritors among actual users, and content edits affect future Reviews.
+
 ## Human approval result presentation
 
 A Reviewer handoff appends an explicit `ask-human` result to the canonical Channel before the Human request, with its captured template identity/version, sanitized input and reason. Record failure still routes to Human; cancellation and owner changes cannot grant authorization. Historical autonomous rejection records remain readable; the historical rejection override cannot accept an `ask-human` record.

docs/architecture/bot-approval-policy.zh.md

@@ -112,6 +112,8 @@ Human 在 Q1–Q18 分轮访谈后确认了完整汇总；原设计树无未决
 
 性能评估：本次只有文档变更，无新依赖、无运行热路径变化，因此免运行性能基准。未来 E2／E3 须分别预算新增准入工作及模型调用，证明确定性命中不调用 Reviewer，并依仓库性能规则验证实际旅程。
 
+#4244 的三部分编辑沿用模板文件 owner 与 32 KiB 有界读取；使用 ADR-0342 记录的 v1 内容表示，旧 Markdown 完整映射为补充说明。复制只复制内容；保存与应用分开，编辑共享原件显示全局继承者在内的使用者。编辑仅影响后续 Review。
+
 ## Human 审批结果展示
 
 Reviewer 转交时，先向同一 canonical Channel 写入显式 `ask-human` 结果，再创建 Human 请求，保留 Review 起始模板身份、版本、已脱敏输入和原因。记录失败仍转 Human；取消或 owner 改变不能授权。历史自动拒绝记录继续可读，旧拒绝覆盖入口不能接受新的 `ask-human` 记录。

docs/bot-cli.md

@@ -2107,3 +2107,21 @@ deepseekbot models allowed [--as <username>]
 ```
 
 Tool effect declarations (E1) preserve the existing tool commands and approval outcomes. Full Access, saved rules, Secrets, device targets and Workspace Grants retain their existing checks; no new route or CLI authority is introduced.
+
+### Three-part approval guidance
+
+Create an empty draft explicitly with `deepseekbot approval-template create my-draft --blank`, or an independent copy with `deepseekbot approval-template create my-copy --from cautious`. No source is selected implicitly; copies retain no origin link. Existing `--file` / `--text-stdin` Markdown input remains supported.
+
+For three-part editing, write a UTF-8 JSON file:
+
+```json
+{
+  "alwaysAsk": ["Send messages or spend money"],
+  "alwaysAllow": ["Read local project files"],
+  "freeText": "Ask me when unsure."
+}
+```
+
+Run `deepseekbot approval-template edit my-draft --parts-file guidance.json`. Read it back with `deepseekbot approval-template show my-draft`; `text` contains the versioned representation. Add `--apply-to <bot-id>` to create/edit to save and then select it for that Bot. Without that flag, saving changes no selection. Applying uses the existing Bot selection authorization; if applying fails, the saved draft remains and can be selected separately.
+
+Editing a shared original affects future Reviews for every Bot in its `usedBy` list, including global inheritors. Copy first to work independently. Always ask has priority over Always allow, then free text supplements both. These are fallible natural-language instructions, never deterministic Tool Approval Rules. Conflicts, missing coverage or uncertainty ask the Human. Legacy Markdown remains intact as free text when converted; already-started Reviews retain their captured content/version.

docs/bot-cli.zh.md

@@ -2048,3 +2048,21 @@ Web 手动检查请求最多等待 25 秒，关闭自检卡片会取消请求。
 公网阶段仅对 DNS、网络、超时及 HTTP 429/5xx 短暂失败重试：最多四次，间隔 1/3/6 秒，仍受同一个 20 秒总时限约束。证书或身份失败不重试。每次自检完成后，界面刷新一次账号电脑列表。
 
 工具效果声明（E1）保持既有工具命令与审批结果。Full Access、保存规则、Secrets、设备目标和 Workspace Grant 仍使用原检查；不新增 route 或 CLI 权限。
+
+### 三部分审批指导
+
+使用 `deepseekbot approval-template create my-draft --blank` 明确创建空白草稿，或使用 `deepseekbot approval-template create my-copy --from cautious` 创建独立副本。不会自动选取来源，副本不保留来源关联。仍支持 `--file`／`--text-stdin` Markdown 输入。
+
+三部分编辑使用 UTF-8 JSON 文件：
+
+```json
+{
+  "alwaysAsk": ["发送消息或花钱"],
+  "alwaysAllow": ["读取本地项目文件"],
+  "freeText": "不确定时问我。"
+}
+```
+
+运行 `deepseekbot approval-template edit my-draft --parts-file guidance.json`，再用 `deepseekbot approval-template show my-draft` 读回；`text` 包含带格式版本的内容。创建／编辑时添加 `--apply-to <bot-id>` 才会在保存后为该 Bot 选用模板。不加时不改变选择。应用仍通过现有 Bot 选择授权；应用失败时已保存的草稿保留，可单独选用。
+
+编辑共享原件影响 `usedBy` 中所有 Bot 的后续 Review，包括全局继承者。需要独立修改时先复制。总是询问优先于总是允许，补充说明不能取消前者。这些是可能被模型误解的自然语言指导，不是确定性 Tool Approval Rules；冲突、未覆盖或不确定均交给 Human。转换时旧 Markdown 完整保留为补充说明，已经开始的 Review 保留捕获的内容和版本。