dsh-perm-gate 2.1.2 → 2.6.2

package/README.md

@@ -26,7 +26,8 @@
 > | DSH version | Branch | Version | npm tag |
 > | --- | --- | --- | --- |
 > | 0.1.0-rc.7 ~ 0.1.1-rc.x | `legacy` | `1.x` | `@legacy` |
-> | 0.1.2-alpha.1+ (incl. 0.1.5-rc.2) | `main` | `2.x` | `@latest` / `@dsh-0.1.2` (`@2.x` is a range) |
+> | 0.1.2-alpha.1 ~ 0.1.5-rc.0 | `main` | `2.x` | `@latest` / `@dsh-0.1.2` (`@2.x` is a range) |
+> | 0.1.5-rc.1+ | `sync/0.1.5-from-main` (=`compat/0.1.5`) | `3.x` | GitHub ref install (no dist-tag yet) |
 >
 > The series number tracks the **DSH line** (`1.x` = DSH ≤ 0.1.1, `2.x` = DSH 0.1.2+),
 > and the majors fence each other: a `^1.x` install never resolves a `2.x` release and
@@ -42,7 +43,7 @@
 > **private** method of the user-approval service on both, so it is read behind a
 > `typeof` probe and degrades to “policy unknown” when absent or throwing.
 
-Version **2.1.2** — see the [Changelog](./CHANGELOG.md).
+Version **2.6.1** — see the [Changelog](./CHANGELOG.md).
 
 A single, self-sufficient, deterministic-first, fail-closed permission gate for DeepSeek Harness.
 
@@ -104,6 +105,31 @@ grants and LLM. It is editable as a list in the settings card (preset entries ar
 one-click restore brings the preset back); unset or empty applies the preset — the blacklist
 never silently turns off.
 
+## Screenshots
+
+**The settings card — the 自动审查 tier.** The front end exposes a single switch; the four back-end
+strategies combine. `LlmAssist` can follow the session's current model or be pinned to a provider /
+model, and carries its own health test and verdict learning:
+
+![Settings card — the 自动审查 tier](assets/setting-head.png)
+![LlmAssist — provider, model, API key](assets/llms.png)
+
+**The rules the gate actually loaded**, read straight from the `dsh-perm-gate-rules` settings
+namespace — the panel is read-only by design, so it can never edit what it shows:
+
+![Built-in rules, read-only](assets/setting-rules.png)
+
+**Approval decision log** — every verdict in this session, newest first, with the reason the model saw:
+
+![Approval decision log](assets/permlist.png)
+
+**Decision strips** — an auto-allow states its basis (a read-only tool, or an LLM `safe` verdict),
+and a stand-down is never silent:
+
+![ALLOW strip — read-only internal tool](assets/allow1.png)
+![ALLOW strip — llm-assist risk: safe](assets/allow2.png)
+![GATE OFF strip — the gate stood down](assets/gateoff.png)
+
 ## Install
 
 Requires an existing [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) installation.
@@ -229,7 +255,16 @@ proxy liveness, env-injection state, block counters, recent blocks).
 自动审查 is an **independent approval tier** in the DSH permission picker, parallel to
 Read Only / Workspace Write / Full access / Whitelist. It is **not** generic "auto-approval" and
 never mints blanket authority: it only narrows or widens the seam *before* the human/LLM step
-while P0 hard-deny stays monotonic and non-negotiable.
+while P0 hard-deny stays monotonic and non-negotiable **within the gate's own scope**.
+
+> **P0 is scoped, not global.** The gate acts only while the session's permission preset is one
+> of `gatePresets` (default `permissive` / `permissive-full`). Under any other preset — Read Only,
+> Workspace Write, or Full access — the **entire** gate stands down, P0 hard-deny included,
+> because the selected tier's own policy governs that session. This is deliberate (see
+> `gatePresets` in the configuration table), but it means "P0 is non-negotiable" holds *inside*
+> the gate's tiers rather than across every tier. A stand-down is not silent: the gate records one
+> `stand-down` event per session/preset transition and the browser shows a sticky **GATE OFF**
+> strip above the input. Set `gatePresets: ['*']` to make P0 global again.
 
 **Two variants ship**, because a preset's `sandbox` and `approval` are independent knobs and
 coupling them forced a bad trade:
@@ -255,9 +290,10 @@ default row and the composer picker) and only supplies its own localized labels
 built-in values, so `cordis.patch.yml` ships the Chinese label for every session.
 
 The **icon** is a different story. The composer's glyph map is closed, and its own comment states
-the rule: *host-configured names outside the design set get none.* `permissive` is a built-in
-value, so 自动审查 already has a shield+eye glyph; `permissive-full` gets the same glyph only
-because `npx dsh-perm-gate-patch-glyph` adds it to that map. That patch edits a **host**
+the rule: *host-configured names outside the design set get none.* Neither tier is a built-in value,
+so both get an icon only because `npx dsh-perm-gate-patch-glyph` adds them to that map — 自动审查
+copies the `workspace-write` glyph, 自动审查（高权限） the `danger-full-access` one, so each tier
+shows the glyph of the file sandbox it actually shares. That patch edits a **host**
 package, so it is lost on every DSH upgrade — see
 [After a DSH upgrade](./INSTALL.md#after-a-dsh-upgrade-re-apply-the-composer-glyph-patch).
 
@@ -326,7 +362,13 @@ optionally overridden with `classifierProvider` / `classifierModel`). A **health
 
 - `safe` → the call is auto-allowed (audited as the `classifier` source); no panel is shown.
 - `risky` + a **hard category** (`deletion`, `credential`, `remote`, `system`, `bulk`) → the call
-  is **auto-denied** without a panel; hard risks are never auto-allowed and never learned.
+  **keeps the human ask**. The classifier **never denies**: the deny path belongs to the
+  deterministic layers alone (P0 hard-deny, the deny-keyword blacklist, explicit `deny:` rules), so
+  a misgraded category is always negotiable instead of an unappealable block. Hard categories stay
+  distinct from `neutral` in one way that matters: they are **never learned**, so repeated
+  approvals can never sediment them into an auto-allow.
+  (Denying on the model's word was measured live: a benign `git commit -F …` graded `remote`
+  produced an auto-deny with no panel and no grant to retry with.)
 - `risky:neutral` → with `riskLearning` enabled (Settings card, off by default), each human
   approval that actually executes (settled via the host's `tools/result` event) counts toward
   a `tool|category` key; once the count reaches `riskThreshold` (default 3) **and** the new
@@ -359,9 +401,10 @@ channel existed), with `tools/result` settling the same ask as a fallback when t
 correlate it. Approvals report the post-approval learning progress (`n`/threshold), and the notice
 strip labels all three terminal states.
 
-自动审查 and 自动审查（高权限） both draw the shield+eye glyph in the picker — the first from DSH's
-built-in map, the second from the host patch the installation guide describes. Without that patch
-the second tier is text-only on every surface; its label and its gating are unaffected.
+自动审查 and 自动审查（高权限） both draw a glyph in the picker — copied from the built-in tiers whose
+file sandbox they share (`workspace-write` and `danger-full-access`) by the host patch the
+installation guide describes. Without that patch both tiers are text-only on every surface; their
+labels and their gating are unaffected.
 
 ### A selectable session tier
 
@@ -393,6 +436,21 @@ The tier is also adjustable at runtime from **Settings → Plugins → 自动审
 namespace live, so a change applies to the next tool call without a restart. This is an
 independent approval class, NOT a generic "auto-approval" mode.
 
+### Rule test (dry-run)
+
+The same page carries a **Rule test** panel: type a tool name and a command, press Test, and the
+gate judges that call against the ruleset it currently has loaded — without running anything and
+without writing any rule. You get the verdict, the matched rule (index and action), the dimensions
+that rule constrains, and the reason.
+
+It reports the effective verdict (the whole P0 → P1 → P2 → P3 → P4 chain) *and* the rule layer's own
+answer, which are not the same thing: a P0 hard-deny or a preset deny-keyword fires before the rule
+chain and leaves no rule index behind, so the panel says "no rule matched" rather than naming an
+unrelated rule. A `0 rules loaded` note means the `rulesFile` path resolved to nothing.
+
+The panel talks to `POST /api/dsh-perm-gate/dry-run`, which is **read-only by construction** — it
+has no write form at all, so testing a rule can never change it.
+
 ## CLI
 
 Dry-run one call against a rules file (no harness needed):

package/README.zh.md

@@ -25,7 +25,8 @@
 > | DSH 版本 | 分支 | 版本号 | npm 标签 |
 > | --- | --- | --- | --- |
 > | 0.1.0-rc.7 ~ 0.1.1-rc.x | `legacy` | `1.x` | `@legacy` |
-> | 0.1.2-alpha.1+（含 0.1.5-rc.2） | `main` | `2.x` | `@latest` / `@dsh-0.1.2` （`@2.x` 是范围） |
+> | 0.1.2-alpha.1 ~ 0.1.5-rc.0 | `main` | `2.x` | `@latest` / `@dsh-0.1.2` （`@2.x` 是范围） |
+> | 0.1.5-rc.1+ | `sync/0.1.5-from-main`（=`compat/0.1.5`） | `3.x` | GitHub ref 安装（暂无 dist-tag） |
 >
 > 版本序列号跟的是 **DSH 线**（`1.x` = DSH ≤ 0.1.1，`2.x` = DSH 0.1.2+），两条大版本互
 > 相隔离：锁在 `^1.x` 的安装绝不会解析到 `2.x`，反之亦然。`engines.dsh` 表达同样的
@@ -39,7 +40,7 @@
 > 线上都是 user-approval 服务的**私有**方法，因此通过 `typeof` 探测读取，缺失
 > 或抛错时降级为「策略未知」。
 
-版本 **2.1.2** —— 变更见 [Changelog](./CHANGELOG.md)。
+版本 **2.6.1** —— 变更见 [Changelog](./CHANGELOG.md)。
 
 一个**单一自足、确定性优先、fail-closed** 的 DeepSeek Harness 权限门插件。
 
@@ -65,6 +66,27 @@
 - **自动审查档位**（机器值 `permissive`）——一个**独立审批模式**（区别于只读、完全权限与白名单档），既不是"自动审批"，也不授予泛化权限。前端只暴露**一个开关**（`permissive`），后台四个审批策略**可组合**、由插件设置决定——仍对 P0 保持 fail-closed。权限下拉框与设置行都按产品名「自动审查」显示；图标见下文（内置档自带，插件档需补丁）。
 - **沙箱提权自动答复**（`trustEscalation`）— 沙箱提权是从 shell / pwsh / edit 工具**体内部**（`tools/pre-execute` 之后）发出的，所以门禁从未见过它，一个它自动放行的调用仍会弹出确认。开启后，门禁以 `callId` 精确匹配已放行调用并直接答复。
 
+## 界面预览
+
+**设置卡片 —— 自动审查档位**：前端只暴露一个开关，后台四个策略可组合；`LlmAssist` 可跟随会话当前模型，也可钉住 Provider / Model，并自带健康测试与裁决学习：
+
+![设置卡片 —— 自动审查档位](assets/setting-head.png)
+![LlmAssist —— Provider / Model / API Key](assets/llms.png)
+
+**门禁实际加载的规则**——直接读自 `dsh-perm-gate-rules` 设置命名空间；面板按设计只读，改不了它显示的内容：
+
+![内置规则（只读）](assets/setting-rules.png)
+
+**权限审批记录**——本会话每一次裁决，最新在上，附带模型看到的理由：
+
+![权限审批记录](assets/permlist.png)
+
+**裁决条**——自动放行会写明依据（只读工具，或 LLM 判定 `safe`）；停摆也绝不静默：
+
+![ALLOW 条 —— 只读内置工具](assets/allow1.png)
+![ALLOW 条 —— llm-assist 判定 safe](assets/allow2.png)
+![GATE OFF 条 —— 门禁停摆](assets/gateoff.png)
+
 ## 安装
 
 需要先安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。
@@ -151,7 +173,14 @@ DSH **自身**的网络流量 —— 内建网络工具与 LLM 传输 —— 刻
 
 自动审查是权限下拉框里一个**独立审批档**，与只读 / 工作区内修改 / 完全权限 / 白名单平行。
 它不是泛化的"自动审批"、也不授予泛化权限：只会在人类/LLM 接缝**之前**收窄或放宽决策，
-P0 硬拒绝始终单调且不可协商。
+P0 硬拒绝在**本门禁自身的档位作用域内**始终单调且不可协商。
+
+> **P0 是档位作用域内的，不是全局的。** 门禁只在会话权限档位属于 `gatePresets`
+> （默认 `permissive` / `permissive-full`）时生效。其他档位 —— 只读、工作区内修改、完全权限
+> —— 下**整个门禁停用，包括 P0 硬拒绝**，因为该档位自身的策略接管了这个会话。这是刻意设计
+> （见配置表的 `gatePresets`），但也就意味着「P0 不可协商」成立于**门禁的档位之内**，而非所有档位。
+> 停用**不是静默的**：每次会话档位切换会记录一条 `stand-down` 事件，浏览器在输入框上方常驻一条
+> **GATE OFF** 提示条。把 `gatePresets` 设为 `['*']` 可让 P0 重新变成全局。
 
 **提供两个变体** —— 因为预设的 `sandbox` 与 `approval` 是两根**独立**旋钮，把它们绑死会逼出
 一个糟糕的取舍：
@@ -173,9 +202,10 @@ MSYS2/Cygwin 的 `sh.exe`、ConPTY 都会以 `Win32 error 5` / `couldn't create
 标签，因此 `cordis.patch.yml` 直接写中文名，对所有会话一致。
 
 **图标是另一回事。** 输入栏的图标表是闭合的，表自己的注释写明了规则：*host-configured names
-outside the design set get none*。`permissive` 是内置值，所以「自动审查」本来就有盾+眼图标；
-「自动审查（高权限）」能拿到同一个图标，靠的是 `npx dsh-perm-gate-patch-glyph` 往那张表里
-加了一项。该补丁改的是**宿主**包，每次 DSH 升级都会丢 —— 见
+outside the design set get none*。两个档位都不是内置值，图标全靠
+`npx dsh-perm-gate-patch-glyph` 往那张表里补两项 ——「自动审查」复制 `workspace-write` 的
+盾+铅笔，「自动审查（高权限）」复制 `danger-full-access` 的盾+感叹号，各自对应自己实际共用的
+文件沙箱。该补丁改的是**宿主**包，每次 DSH 升级都会丢 —— 见
 [DSH 升级后：重打输入区图标补丁](./INSTALL.zh.md)。
 
 `cordis.yml`：
@@ -252,7 +282,8 @@ LLM 评定为 `safe` 且门禁自动放行的调用因此仍会弹出确认。
 开启 `llmAssist` 后，接收 LLM（自定义 OpenAI 兼容端点，或 DSH 宿主模型组——见上文）按结构化协议逐条评估 `ask`。**判定发生在门禁的 `tools/pre-execute` 瀑布内部、决策返回宿主之前**：`safe` 直接放行，审批面板根本不会出现；只有真正无法确定的判定才会弹到你面前。
 
 - `safe` → 自动放行（审计来源为 `classifier`），不弹面板。
-- `risky` + **硬风险类别**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ **自动拒绝**、不弹面板；硬风险永不自动放行、也永不进入学习。
+- `risky` + **硬风险类别**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ **维持人工确认（ask）**。分类器**永不拒绝**：拒绝只属于确定性层（P0 硬拒绝、黑名单关键词、显式 `deny:` 规则），所以被误判的类别永远可协商，而不会变成无法申诉的封禁。硬类别与 `neutral` 仅保留一条关键区别：**永不进入学习**，因此反复确认也不可能把它沉淀成自动放行。
+  （拿模型的判断当拒绝依据是实测出来的问题：一条无害的 `git commit -F …` 被判 `remote`，直接自动拒绝——没有面板、也没有可重试的授权入口。）
 - `risky:neutral` → 若开启 `riskLearning`（设置卡片内，默认关闭），人工批准且真实执行的 neutral 风险会按 `tool|类别` 计数；计数达到 `riskThreshold`（默认 3）且新调用的操作指纹（命令词 + 目标基名）命中已确认样本时，**同一操作**自动放行。不同目标永不复用该放行。开启学习沉淀（`riskSediment`，默认开）后，满阈值 key 的确认样本会成为**确定性放行规则**：指纹精确命中即直接放行、无需再过 LLM——即使关闭 llmAssist 也继续生效；沉淀规则在设置卡片中可见、可管理（终止学习 / 删除样本）。
 - 超时（`riskTimeoutMs`，默认 20s，重试 1 次）、传输失败与协议外输出均维持原 `ask`——门禁绝不猜测。
 
@@ -267,9 +298,9 @@ LLM 评定为 `safe` 且门禁自动放行的调用因此仍会弹出确认。
 调用文本命中任一关键词（大小写不敏感子串）即直接拒绝，且先于白名单 / 授权 / LLM。黑名单在设置
 卡片中按列表查看与增删（预置条目带标签，可一键恢复预置）；未设置或为空时应用预置列表——黑名单
 不会静默关闭。
-「自动审查」与「自动审查（高权限）」在选择器里都画盾+眼图标 —— 前者来自 DSH 内置表，后者来自
-安装指南里描述的那次宿主补丁。没有该补丁时，第二个档位在所有界面上都是纯文字；它的标签与门禁
-不受影响。
+「自动审查」与「自动审查（高权限）」在选择器里都画图标 —— 图标由安装指南里描述的那次宿主补丁
+从各自共用的文件沙箱档位复制而来（`workspace-write` 与 `danger-full-access`）。没有该补丁时，
+两个档位在所有界面上都是纯文字；它们的标签与门禁不受影响。
 
 
 ## CLI（独立 dry-run）

package/cordis.patch.yml

@@ -17,14 +17,17 @@
 # The composer's permission picker draws an icon per preset from a CLOSED map
 # inside @deepseek-ai/dsh-client-ui-conversation (`permissionGlyphs`), whose
 # source states the rule: "host-configured names outside the design set get
-# none". DSH ships a shield+eye glyph for `permissive`, so 自动审查 has an icon,
-# but a second plugin tier has none — it falls back to text in the trigger. The
-# map is a closure variable with no plugin-facing seam (the option objects the
-# host supplies carry only {value, name, description}), so the only way to give
-# BOTH tiers the same glyph is to extend that map.
-# `scripts/patch-permission-glyph.mjs` does exactly that, duplicating the
-# `permissive` entry under `permissive-full`. It patches a HOST package, so it
-# must be re-run after any DSH upgrade or reinstall.
+# none". Neither tier is a built-in value, so DSH renders no glyph for either
+# — the map is a closed closure variable and its only plugin-facing input is
+# {value, name, description} on the option objects, which carries no icon. The
+# only way to give a tier an icon is to add an entry to that map.
+# `scripts/patch-permission-glyph.mjs` does exactly that, copying the glyph of
+# the built-in tier whose file sandbox each of ours shares:
+#   permissive       <- ["workspace-write",  (same sandbox: workspace-write)
+#   permissive-full  <- [FULL_ACCESS,        (same sandbox: danger-full-access)
+# The source key is RESOLVED, not assumed (0.1.2 keyed a `permissive` glyph that
+# 0.1.5 dropped, so a literal anchor died with "anchor not found"). It patches a
+# HOST package, so it must be re-run after any DSH upgrade or reinstall.
 #
 # The DSH bundle patch REPLACES the whole `permission.config.presets` map (it
 # does not merge per key), so this file MUST restate every tier that should

package/docs/baseline-guard.md

@@ -0,0 +1,56 @@
+# Baseline Snapshot: feat/capability-absorption
+
+> Captured at T0.3/T0.4 on 2026-09-15
+>
+> **为什么这份快照留在仓库里**：下面那 30 个测试文件是能力吸收（6 维度 / 网络执行面 / 热重载）
+> 落地**之前**的既有覆盖，充当回归护栏——新增行为**不得**靠修改它们来适配。
+> 原位置 `.agents/baseline-snapshot.md` 未入库（`.agents/` 是仓库惯例的本地目录），
+> 2026-09-17 迁到 `docs/` 以便随包分发、可追溯。
+> 注意：仓库当前已有 **40** 个测试文件；本列表是**护栏基线**，不是当前全量清单。
+
+## Gate Status
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| typecheck | ✅ 0 errors | After pre-existing fix commit |
+| test | ✅ 278/278 | 30 spec files |
+| build | ✅ tsc + tsdown | client.js 99.95 kB |
+| lint | ✅ 0 errors | — |
+
+## Pre-existing Fixes (committed)
+
+- `src/risk.ts:137-138` — cast `req.args` to `Record<string, unknown>` (was `{}`)
+- `src/runtime.ts:26` — add `import { decomposeShellCommand } from './shell.js'`
+
+## Test File List (30 files, DO NOT modify to accommodate new behavior)
+
+1. audit.spec.ts
+2. auto-allow-tools.spec.ts
+3. compiler.spec.ts
+4. custom-llm.spec.ts
+5. data-home.spec.ts
+6. deny-keywords.spec.ts
+7. deny-keywords-scope.spec.ts
+8. engine.spec.ts
+9. evaluate.spec.ts
+10. events.spec.ts
+11. feature.spec.ts
+12. grant.spec.ts
+13. host-llm.spec.ts
+14. learning.spec.ts
+15. manual-approval.spec.ts
+16. patch-presets.spec.ts
+17. permissive.spec.ts
+18. pre-execute.spec.ts
+19. preset-scope.spec.ts
+20. review.spec.ts
+21. risk.spec.ts
+22. rule.spec.ts
+23. runtime.spec.ts
+24. runtime-risk.spec.ts
+25. sediment.spec.ts
+26. session-resolution.spec.ts
+27. session-sweep.spec.ts
+28. session-sweep-apply.spec.ts
+29. shell.spec.ts
+30. write-path.spec.ts

package/docs/plan-rules-to-settings.md

@@ -0,0 +1,217 @@
+# Plan: rules.yml → DSH Settings Namespace Migration
+
+## Goal
+
+Eliminate the external `rules.yml` file dependency by migrating rules into the DSH settings namespace (`dsh-perm-gate.rules`). This solves the cold-start directory problem at the root cause: settings are managed by the framework and loaded before any plugin `apply()` runs.
+
+## Current Architecture
+
+```
+User edits rules.yml (or allowlist card writes to it)
+  ↓
+resolveRulesFile() → path string
+  ↓
+readFileSafe() → raw YAML text
+  ↓
+parsePermissionsDocument() → structured doc
+  ↓
+compileDocument() → CompiledRuleset
+  ↓
+PermGateRuntime.decide() → verdict
+```
+
+Read-only view:
+```
+GET /api/dsh-perm-gate/rules
+  → readRulesView(rulesFile)
+    → statSync + readFileSync + parse + compile
+    → RulesView { path, exists, bytes, hash, raw, counts, error }
+```
+
+Write path (allowlist card):
+```
+appendAllowCommand() / replaceAllowCommands()
+  → readFileSync → parse → mutate → stringify → writeFileSync
+```
+
+## Target Architecture
+
+```
+User edits via settings card (or API)
+  ↓
+settings.get('dsh-perm-gate.rules') → structured object (already parsed)
+  ↓
+compileDocument(rules) → CompiledRuleset
+  ↓
+PermGateRuntime.decide() → verdict
+```
+
+Read-only view:
+```
+GET /api/dsh-perm-gate/rules
+  → settings.get('dsh-perm-gate.rules')
+    → RulesView { source: 'settings', rules: {...}, counts, hash }
+```
+
+Write path (allowlist card):
+```
+settings.update({ rules: { allow: [...] } })
+  → framework persists to settings.yaml
+  → settings.watch() triggers reload
+```
+
+## Schema (config.ts)
+
+```typescript
+// New settings schema for rules
+const RuleEntrySchema = z.object({
+  command: z.array(z.string()).optional(),
+  args: z.array(z.string()).optional(),
+  tools: z.array(z.string()).optional(),
+  network: z.object({
+    domains: z.array(z.string()),
+  }).optional(),
+  reason: z.string().default(''),
+})
+
+const RulesSchema = z.object({
+  defaultAction: z.enum(['allow', 'deny', 'ask']).default('ask'),
+  deny: z.array(RuleEntrySchema).default([]),
+  allow: z.array(RuleEntrySchema).default([]),
+  ask: z.array(RuleEntrySchema).default([]),
+  network: z.object({
+    domains: z.array(z.string()).default([]),
+  }).optional(),
+}).default({ defaultAction: 'ask', deny: [], allow: [] })
+```
+
+## Migration Steps
+
+### Phase 1: Dual-Source (backward compatible)
+
+1. **Add `rules` to settings schema** — new field in `dsh-perm-gate` namespace
+2. **Runtime reads from settings first, falls back to file** — `settings.get('rules') ?? loadRulesFile()`
+3. **Allowlist card writes to settings** — `settings.update({ rules: { allow: [...] } })`
+4. **Rules view serves from settings** — `readRulesView()` reads from settings object, not file
+5. **Module-level: still create dataDir** — belt-and-suspenders for the transition period
+
+### Phase 2: File Deprecation
+
+6. **Log deprecation warning** — when `rulesFile` is configured, warn that it's deprecated
+7. **Import button** — UI can import existing `rules.yml` into settings
+8. **Export button** — UI can export settings rules as YAML for version control
+
+### Phase 3: File Removal
+
+9. **Remove `rulesFile` config option** — no longer accepted
+10. **Remove file I/O code** — `allowlist.ts`, `rules-view.ts` file operations
+11. **Remove chokidar watcher** — settings has built-in `watch()`
+12. **Remove dataDir bootstrap** — no longer needed
+
+## How the Read-Only View Changes
+
+### Before (file-based)
+
+```json
+{
+  "path": "C:\\Users\\joshua\\.dsh\\perm-gate\\rules.yml",
+  "exists": true,
+  "bytes": 1513,
+  "hash": "abc123...",
+  "lines": 61,
+  "raw": "permissions:\n  defaultAction: ask\n  deny:\n    ...",
+  "truncated": false,
+  "defaultAction": "ask",
+  "counts": { "allow": 11, "deny": 1, "ask": 0 },
+  "error": null
+}
+```
+
+### After (settings-based)
+
+```json
+{
+  "source": "settings",
+  "defaultAction": "ask",
+  "counts": { "allow": 11, "deny": 1, "ask": 0 },
+  "hash": "abc123...",
+  "rules": {
+    "defaultAction": "ask",
+    "deny": [
+      { "tools": ["shell", "pwsh"], "command": ["rm#recursive"], "reason": "destructive" }
+    ],
+    "allow": [
+      { "command": ["grep"], "reason": "permissive allowlist" }
+    ],
+    "network": {
+      "domains": ["github.com", "registry.npmjs.org"]
+    }
+  }
+}
+```
+
+**Key differences:**
+- `path` / `exists` / `bytes` / `raw` / `truncated` → removed (no file)
+- `source: 'settings'` → added (provenance)
+- `rules` → the structured object (already parsed, not raw YAML)
+- `counts` / `defaultAction` / `hash` → kept (useful for UI)
+
+## How the Allowlist Write Path Changes
+
+### Before (file-based)
+
+```typescript
+// appendAllowCommand reads YAML, mutates, writes back
+appendAllowCommand(rulesFile, 'git push', 'permissive allow-everywhere')
+// → readFileSync → parse → push → stringify → writeFileSync
+```
+
+### After (settings-based)
+
+```typescript
+// Direct settings update
+const current = settings.get('dsh-perm-gate.rules')
+const allow = [...(current.allow ?? []), { command: ['git push'], reason: 'permissive allow-everywhere' }]
+settings.update({ rules: { ...current, allow } })
+// → framework persists → settings.watch() triggers reload
+```
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `src/config.ts` | Add `RulesSchema`, keep `resolveRulesFile` for backward compat |
+| `src/index.ts` | Read from settings first, fall back to file; register settings schema |
+| `src/runtime.ts` | Accept `rules` object directly (no file read) |
+| `src/rules-view.ts` | Add `readRulesViewFromSettings()` |
+| `src/allowlist.ts` | Add `appendAllowToSettings()`, `replaceAllowInSettings()` |
+| `src/events.ts` | Update `registerRulesRoute` to use settings view |
+| `src/watch.ts` | Remove chokidar watcher (settings has built-in watch) |
+
+## Cold-Start Resilience (All Plugins)
+
+The same pattern should be applied to other plugins that read files at startup:
+
+| Plugin | Data | Risk | Fix |
+|---|---|---|---|
+| `dsh-perm-gate` | rules.yml | HIGH | Settings migration (this plan) |
+| `dsh-search-index` | index files | MEDIUM | dataDir bootstrap + try/catch |
+| `dsh-session-guard` | guard config | LOW | Already settings-backed |
+| `dsh-prime-memory` | memory files | MEDIUM | dataDir bootstrap + try/catch |
+| `dsh-context-compression` | config | LOW | Already settings-backed |
+
+**Universal pattern:**
+1. Module-level `ensureDataDir()` — belt
+2. Read paths: `dataDirReady()` check → empty defaults if missing
+3. Write paths: `ensureDataDir()` before first write
+4. All file reads wrapped in try/catch with graceful fallback
+
+## Testing
+
+- [ ] Unit: `compileDocument` with settings-sourced rules (same as YAML-sourced)
+- [ ] Unit: `readRulesViewFromSettings` returns correct `RulesView`
+- [ ] Unit: `appendAllowToSettings` correctly mutates settings object
+- [ ] Integration: settings card reads and displays rules
+- [ ] Integration: allowlist card writes persist to settings
+- [ ] Migration: existing `rules.yml` imports into settings correctly
+- [ ] Cold start: plugin loads with empty settings (no rules configured)