dsh-rules 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rj-jiangyichen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# dsh-rules
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DSH Plugin topic](https://img.shields.io/badge/topic-dsh--plugin-blue)](https://github.com/topics/dsh-plugin)
+
+**English** | [中文](./README.zh.md)
+
+Glob-activated rule prompts for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) — a Claude Code `rules.md` / `# Path:`-style mechanism. Each rule declares glob patterns; when the agent **reads or edits** a matching file, the rule activates and its content (any prompt or markdown document) is injected into the conversation as a superseding `<rules>` snapshot.
+
+> Works in **every DSH deployment**: desktop / web / tui / headless / custom profiles — nothing about this plugin is desktop-specific.
+
+## Contents
+
+- [Features](#features)
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Rule format](#rule-format)
+- [Configuration](#configuration)
+- [Discoverability](#discoverability)
+- [Limitations](#limitations)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- **Glob activation** — rules activate per file the agent touches: `**`, `*`, `?`, `{a,b}`, `[abc]`, and `!` negation (picomatch).
+- **Claude Code compatible** — plain rule files (`.dsh/rules/*.md`) *and* `# Path:` sections inside `CLAUDE.md` / `AGENTS.md`.
+- **Visible & durable** — active rules are injected as a user message the UI shows and the session log persists; each snapshot supersedes earlier ones, so the model always sees the current set.
+- **Budget-bounded** — byte-budget rendering (32 KB default): low-priority rules are dropped first, then the last rule is truncated; content is escaped so it can never break out of the framing tags.
+- **Resume-friendly** — on session resume the last snapshot and its matched files are restored from the log, preventing duplicate injection.
+- **Per-session tracking** — every agent/session tracks its own touched files (subagents included); global rules (no `path:`) are always active.
+
+## How it works
+
+```
+workspace
+  .dsh/rules/*.md    ← rule definitions (frontmatter declares globs)
+  ~/.dsh/rules/*.md  ← user-level rules (optional)
+  CLAUDE.md          ← optional: # Path: sections (Claude Code compatible)
+
+agent reads/edits a file (fs/observed) → record per-session touched path
+  ↓ every step (agent/pre-step)
+match touched paths against globs → collect active rules → render a <rules> snapshot into the conversation
+```
+
+- **Injection point**: an `agent/pre-step` waterfall listener appends a `<rules>`-framed user message; a new message is only appended when the snapshot text changes.
+- **Discovery & caching**: rule sources are re-probed per step with version caching (`fs.stat().version`, or `mtimeMs:size` on the Node fallback) — edits to rule files take effect on the next step.
+- **Reads**: prefer the harness `fs` service (containment-aware); fall back to Node's filesystem when no `fs` service is mounted.
+
+## Installation
+
+### Any DSH deployment (generic)
+
+Published on the npm registry — `dsh plugin` installs **and activates** the plugin in one step:
+
+```powershell
+# Adjust the profile name: desktop / web / tui / headless
+dsh plugin --profile desktop add dsh-rules
+```
+
+The package declares `dsh.bundle.patch`, so the reconcile pass of `dsh plugin add` appends `dsh-rules` to the profile's `dsh.profile.bundles` layer list automatically — **no manual `cordis.patch.yml` edits are needed**. Restart DSH (restart the desktop app; restart the web/headless process) and the plugin loads with the next Cordis composition.
+
+Updates: `dsh plugin --profile desktop update dsh-rules` (or remove + add).
+
+Installing from a local checkout (development):
+
+```powershell
+# From the repo root — activates the bundle automatically, same as the registry install
+dsh plugin --profile desktop add .
+```
+
+> ⚠️ pnpm splits `add` arguments on spaces, so a repository **path containing spaces** must be installed through a no-space junction (see below).
+
+### DSH Desktop (Windows) one-click script
+
+```powershell
+# 1. Clone this repository, then from the repo root:
+node scripts\install-desktop.mjs
+
+# 2. Restart DSH Desktop — the plugin loads with the next Cordis composition
+```
+
+The script creates a no-space junction to the repo and runs the desktop app's own `dsh plugin add` through it (pnpm splits `add` arguments on spaces, so a repository path containing spaces must go through the junction):
+
+```powershell
+# 0) Create a no-space junction to the repository (needed when the path contains spaces)
+mklink /J "C:\code_repos\dsh-rules" "C:\code_repos\dsh rules plugin"
+
+# 1) Install via the desktop's own dsh command (through the junction path)
+& "C:\Program Files\DSH Desktop\DSH Desktop.exe" --expose-internals `
+  "C:\Program Files\DSH Desktop\resources\app.asar.unpacked\lib\desktop-cli.js" `
+  plugin --profile desktop add "C:\code_repos\dsh-rules"
+```
+
+Per-profile configuration (optional): the plugin loads with its code defaults; to customize, override the entry's `config` in `<profile>/cordis.patch.yml`:
+
+```yaml
+- id: dsh-rules
+  name: dsh-rules
+  config:
+    includeClaudeSections: true
+    projectRootMarkers: [".git", ".dsh"]
+```
+
+**Uninstall**: `node scripts\install-desktop.mjs --uninstall` (or `dsh plugin --profile desktop remove dsh-rules`), then restart the app. Installing/uninstalling never touches the DSH installation directory (`resources\app.asar.unpacked`) — only profile configuration, fully reversible.
+
+## Rule format
+
+### Source A: rule files (`.dsh/rules/*.md` and `~/.dsh/rules/*.md`)
+
+```markdown
+---
+path:
+  - "src/**/*.ts"
+  - "!src/**/*.test.ts"
+---
+Rule body (markdown, injected verbatim when active — any prompt content works)
+```
+
+| Frontmatter field | Description |
+| --- | --- |
+| `path` | String or list of globs, relative to the project root, `/` separators; `!` prefixes mark exclusion patterns. **Absent or empty = always-active global rule** (active for any session in the workspace). |
+| `name` | Optional; rule identity (used for same-name deduplication). Defaults to the file name without `.md`. |
+
+### Source B: `# Path:` sections (requires `includeClaudeSections: true`)
+
+Parses `# Path: <globs…>` headings out of `AGENTS.md` / `CLAUDE.md` (including `.local.md` variants and `~/.dsh/AGENTS.md`):
+
+```markdown
+# Project notes (content before the first heading is handled by the built-in agent-instructions baseline, not by this plugin)
+
+# Path: src/**/*.ts, scripts/**
+This section activates only when a file under src/**/*.ts or scripts/ is touched
+```
+
+- Each `# Path:` heading starts a rule that runs until the next heading (or end of file).
+- Globs may be comma- or space-separated.
+- Content before the first `# Path:` heading is intentionally **not** injected by this plugin — DSH's built-in `agent-instructions` already injects the full AGENTS.md/CLAUDE.md baseline.
+
+### Precedence & deduplication
+
+Project rules (rank 100) > user rules (rank 200) > `# Path:` sections (rank 300). Same-name rules keep the highest-priority entry; rendering order is (rank, name) — deterministic across steps.
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `dshHome` | `$DSH_HOME` / `~/.dsh` | Root for user rules and `~/.dsh/AGENTS.md` |
+| `projectRootMarkers` | `[".git"]` | Marker files/dirs used to find the project root by walking up |
+| `ruleDirNames` | `[".dsh/rules"]` | Rule directories inside the project (relative to the project root, multiple allowed) |
+| `includeUserRules` | `true` | Enable `~/.dsh/rules/*.md` |
+| `includeClaudeSections` | `false` | Parse `# Path:` sections |
+| `instructionFileCandidates` | `["AGENTS.md", "CLAUDE.md"]` | Candidate file names for `# Path:` sections |
+| `localInstructionFileCandidates` | `["AGENTS.local.md", "CLAUDE.local.md"]` | Per-directory candidate file names |
+| `maxBytes` | `32768` | Per-injection render budget (UTF-8 bytes); `<= 0` disables the plugin |
+| `maxSourceBytes` | `1048576` | Per-rule source size cap; larger files are skipped |
+| `maxTouchedPaths` | `512` | Touched-path cap per session (FIFO eviction) |
+
+## Discoverability
+
+This plugin is discoverable through the GitHub [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic — the channel recommended by the [DeepSeek Harness README](https://github.com/deepseek-ai/deepseek-harness) ("Community and support": *Add the `dsh-plugin` topic to your plugin repository for discoverability*). Community plugin lists and marketplaces (e.g. awesome-dsh-plugin, dsh-plugin-marketplace) scan that topic to pick up new plugins; the tag can be viewed/edited in the repository's About section.
+
+## Limitations
+
+- Only files **inside the project root** can activate rules; reads outside the root never trigger (avoids `../` false positives).
+- The touched-path set is in-memory: after resuming a session, rules re-activate as the agent re-reads files (the previously matched list is restored from the log).
+- Deployments with `includeRuntimeContext: false` are unaffected — this plugin injects its own message and does not depend on the runtime-context snapshot.
+- Rules are injected as "superseding snapshot" messages; the session log retains historical snapshots, but each snapshot is the complete current set and the model follows the latest one.
+
+## Development
+
+```powershell
+pnpm install
+pnpm test        # node --test: parsing / glob matching / precedence / budget / determinism / fs fallback
+```
+
+Layout:
+
+- `lib/index.js` — plugin entry (`name` / `Config` / `apply`): `fs/observed` touch tracking, `agent/pre-step` injection, `agent/disposed` cleanup.
+- `lib/rules.js` — pure logic: frontmatter and `# Path:` parsing, glob compilation/matching, precedence merging, budget rendering.
+- `lib/fs.js` — versioned discovery/reads: harness `fs` service first, Node fallback.
+- `test/rules.test.mjs` — unit tests.
+- `examples/.dsh/rules/` — sample rules (copy into your project to get started).
+- `fixtures/demo-project/` — a ready-made project for trying the plugin out.
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,188 @@
+# dsh-rules
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DSH Plugin topic](https://img.shields.io/badge/topic-dsh--plugin-blue)](https://github.com/topics/dsh-plugin)
+
+[English](./README.md) | **中文**
+
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的 rules 插件：**通过 glob 匹配文件路径，激活对应的提示词 / markdown 文档**，对标 Claude Code 的 `rules.md` / `# Path:` 规则机制。每条规则声明 glob 模式；当 agent **读取或编辑**了匹配文件时规则激活，其内容（任意提示词或 markdown 文档）作为一条"取代旧快照"的 `<rules>` 用户消息注入对话。
+
+> 适用于**所有 DSH 部署**：desktop / web / tui / headless / 自定义 profile——插件本身没有任何 desktop 专属依赖。
+
+## 目录
+
+- [特性](#特性)
+- [工作原理](#工作原理)
+- [安装](#安装)
+- [规则格式](#规则格式)
+- [配置项](#配置项)
+- [发现与收录](#发现与收录)
+- [已知限制](#已知限制)
+- [开发](#开发)
+- [许可证](#许可证)
+
+## 特性
+
+- **glob 激活** —— 按 agent 触碰的文件逐个激活规则：`**`、`*`、`?`、`{a,b}`、`[abc]`、`!` 取反（picomatch）。
+- **Claude Code 兼容** —— 既支持规则文件（`.dsh/rules/*.md`），也支持 `CLAUDE.md` / `AGENTS.md` 内的 `# Path:` 段落。
+- **可见且持久** —— 激活的规则以用户消息注入，UI 可见、会话日志持久化；每个快照取代更早快照，模型始终看到最新集合。
+- **预算可控** —— 字节预算渲染（默认 32 KB）：先丢弃低优先级规则，再截断最后一条；正文转义，无法逃逸框架标签。
+- **恢复友好** —— 恢复会话时从日志恢复最近一次快照与已匹配文件列表，避免重复注入。
+- **按会话跟踪** —— 每个 agent/会话独立跟踪触碰文件（含子代理）；无 `path:` 的全局规则恒激活。
+
+## 工作原理
+
+```
+工作区
+  .dsh/rules/*.md    ← 规则定义（frontmatter 声明 glob）
+  ~/.dsh/rules/*.md  ← 用户级规则（可选）
+  CLAUDE.md          ← 可选：# Path: 段落（Claude Code 兼容）
+
+agent 读取/编辑文件（fs/observed）→ 记录每会话触碰路径
+  ↓ 每个 step（agent/pre-step）
+按 glob 匹配触碰路径 → 收集激活规则 → 渲染 <rules> 快照注入对话
+```
+
+- **注入点**：`agent/pre-step` 瀑布监听器追加一条 `<rules>` 框架的用户消息；快照文本变化时才注入新消息。
+- **发现与缓存**：每个 step 重新探测规则源并做版本缓存（`fs.stat().version`，Node 回退为 `mtimeMs:size`）——规则文件改动在下一步即生效。
+- **读取**：优先 harness `fs` 服务（遵守沙箱约束）；无 `fs` 服务时回退 Node 文件系统。
+
+## 安装
+
+### 通用安装（任意 DSH 部署）
+
+已发布到 npm registry —— `dsh plugin` 一步完成安装**并激活**：
+
+```powershell
+# profile 名按你的部署调整：desktop / web / tui / headless
+dsh plugin --profile desktop add dsh-rules
+```
+
+插件包声明了 `dsh.bundle.patch`，`dsh plugin add` 的 reconcile 步骤会自动把 `dsh-rules` 追加到 profile 的 `dsh.profile.bundles` 层列表——**无需手动编辑 cordis.patch.yml**。重启 DSH（桌面版重启应用；web/headless 重启进程），插件随下次 Cordis 组合加载。
+
+更新：`dsh plugin --profile desktop update dsh-rules`（或 remove 后 add）。
+
+从本地仓库安装（开发模式）：
+
+```powershell
+# 在仓库根目录执行——同样自动激活 bundle
+dsh plugin --profile desktop add .
+```
+
+> ⚠️ pnpm 会按空格拆分 `add` 参数，仓库**路径含空格**时必须通过无空格 junction 安装（见下）。
+
+### DSH Desktop（Windows）一键脚本
+
+```powershell
+# 1. 克隆本仓库后，在仓库根目录执行：
+node scripts\install-desktop.mjs
+
+# 2. 重启 DSH Desktop（插件在下次启动时随 Cordis 组合加载）
+```
+
+脚本会创建指向仓库的无空格 junction，并通过它执行桌面自带的 `dsh plugin add`（pnpm 按空格拆分 `add` 参数，路径含空格时必须走 junction）：
+
+```powershell
+# 0) 为仓库创建无空格 junction（路径含空格时需要）
+mklink /J "C:\code_repos\dsh-rules" "C:\code_repos\dsh rules plugin"
+
+# 1) 用桌面自带的 dsh 命令把插件装进 profile（经 junction 路径）
+& "C:\Program Files\DSH Desktop\DSH Desktop.exe" --expose-internals `
+  "C:\Program Files\DSH Desktop\resources\app.asar.unpacked\lib\desktop-cli.js" `
+  plugin --profile desktop add "C:\code_repos\dsh-rules"
+```
+
+按 profile 自定义配置（可选）：插件按代码默认值加载；如需定制，在 `<profile>/cordis.patch.yml` 里以 id 定位覆盖该条目的 `config`：
+
+```yaml
+- id: dsh-rules
+  name: dsh-rules
+  config:
+    includeClaudeSections: true
+    projectRootMarkers: [".git", ".dsh"]
+```
+
+**卸载**：`node scripts\install-desktop.mjs --uninstall`（或 `dsh plugin --profile desktop remove dsh-rules`），再重启应用。安装/卸载均不修改 DSH 安装目录（`resources\app.asar.unpacked`），只动 profile 配置，可随时回滚。
+
+## 规则格式
+
+### 来源 A：规则文件（`.dsh/rules/*.md` 与 `~/.dsh/rules/*.md`）
+
+```markdown
+---
+path:
+  - "src/**/*.ts"
+  - "!src/**/*.test.ts"
+---
+规则正文（markdown，激活时原样注入，可以是任意提示词内容）
+```
+
+| frontmatter 字段 | 说明 |
+| --- | --- |
+| `path` | 字符串或字符串数组；glob 相对项目根、使用 `/` 分隔符；`!` 前缀为排除模式。**缺省或为空 = 全局常驻规则**（工作区任意会话都激活）。 |
+| `name` | 可选；规则标识（用于同名规则去重），缺省取文件名（去掉 `.md`）。 |
+
+### 来源 B：`# Path:` 段落（需 `includeClaudeSections: true`）
+
+从 `AGENTS.md` / `CLAUDE.md`（含 `.local.md`，以及 `~/.dsh/AGENTS.md`）中解析 `# Path: <glob…>` 标题段落：
+
+```markdown
+# 项目说明（此段之前的内容交给 agent-instructions 基线处理，本插件不注入）
+
+# Path: src/**/*.ts, scripts/**
+本段仅在触碰 src 下 .ts 或 scripts 下文件时激活
+```
+
+- 每个 `# Path:` 标题之后直到下一个标题（或文件尾）是一条规则。
+- glob 支持逗号或空格分隔。
+- 首个 `# Path:` 之前的内容**不**由本插件注入（DSH 内置的 `agent-instructions` 已负责注入 AGENTS.md/CLAUDE.md 基线全文）。
+
+### 优先级与去重
+
+项目规则（rank 100）> 用户规则（rank 200）> `# Path:` 段落（rank 300）。同名规则仅保留最高优先级者；渲染顺序按（rank, 名称）确定，保证跨 step 稳定。
+
+## 配置项
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `dshHome` | `$DSH_HOME` / `~/.dsh` | 用户级规则与 `~/.dsh/AGENTS.md` 所在根目录 |
+| `projectRootMarkers` | `[".git"]` | 向上寻找项目根的标记文件/目录 |
+| `ruleDirNames` | `[".dsh/rules"]` | 项目内规则目录（相对项目根，可多个） |
+| `includeUserRules` | `true` | 是否启用 `~/.dsh/rules/*.md` |
+| `includeClaudeSections` | `false` | 是否解析 `# Path:` 段落 |
+| `instructionFileCandidates` | `["AGENTS.md", "CLAUDE.md"]` | `# Path:` 段落候选文件名 |
+| `localInstructionFileCandidates` | `["AGENTS.local.md", "CLAUDE.local.md"]` | 目录级候选文件名 |
+| `maxBytes` | `32768` | 每次注入的渲染预算（UTF-8 字节），`<= 0` 关闭插件 |
+| `maxSourceBytes` | `1048576` | 单条规则源文件大小上限，超出跳过 |
+| `maxTouchedPaths` | `512` | 每会话记录的触碰路径上限（FIFO 淘汰） |
+
+## 发现与收录
+
+本插件通过 GitHub [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic 被 DSH 生态发现——这是 [DeepSeek Harness 官方 README](https://github.com/deepseek-ai/deepseek-harness) "Community and support" 章节推荐的插件收录渠道（*Add the `dsh-plugin` topic to your plugin repository for discoverability*）。社区插件列表与市场（如 awesome-dsh-plugin、dsh-plugin-marketplace）据此自动扫描收录；仓库 About 栏可查看/添加该标签。
+
+## 已知限制
+
+- 只有**项目根内**的文件能激活规则；读取项目外文件不触发（避免 `../` 误匹配）。
+- 触碰集合是内存态：恢复会话后，规则随 agent 重新读取文件逐步重新激活（已匹配文件列表会从日志恢复）。
+- `includeRuntimeContext: false` 的部署不受影响（本插件注入独立消息，不依赖运行时上下文快照）。
+- 规则注入为"取代旧快照"的消息流，会话日志中会保留历史快照；每个快照本身是完整集合，模型以最新快照为准。
+
+## 开发
+
+```powershell
+pnpm install
+pnpm test        # node --test：解析 / glob / 优先级 / 预算 / 确定性 / fs 回退
+```
+
+代码结构：
+
+- `lib/index.js` — 插件入口（`name` / `Config` / `apply`）：`fs/observed` 触碰跟踪、`agent/pre-step` 注入、`agent/disposed` 清理。
+- `lib/rules.js` — 纯函数：frontmatter 与 `# Path:` 解析、glob 编译匹配、优先级合并、预算渲染。
+- `lib/fs.js` — 版本化发现/读取：优先 harness `fs` 服务，缺失时回退 Node fs。
+- `test/rules.test.mjs` — 单元测试。
+- `examples/.dsh/rules/` — 示例规则（可直接复制到项目使用）。
+- `fixtures/demo-project/` — 现成的体验项目。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# dsh-rules bundle layer: register the glob-activated rules plugin
+# (Claude Code rules.md style) into the host plane.
+#
+# This layer is applied by the profile loader because package.json declares
+# `dsh.bundle.patch`; `dsh plugin --profile <name> add dsh-rules` therefore
+# activates the plugin automatically — no manual cordis.patch.yml edits are
+# needed in the target profile.
+#
+# Per-profile customization (e.g. `includeClaudeSections: true`, extra
+# `projectRootMarkers`) belongs in the profile's own cordis.patch.yml as an
+# id-targeted override of this entry's `config`:
+#
+#   - id: dsh-rules
+#     name: dsh-rules
+#     config:
+#       includeClaudeSections: true
+#       projectRootMarkers: [".git", ".dsh"]
+- insert:
+    - id: dsh-rules
+      name: dsh-rules

package/lib/fs.js

@@ -0,0 +1,195 @@
+/**
+ * Filesystem helpers for the dsh-rules plugin.
+ *
+ * Reads prefer the harness `fs` service (which respects containment and
+ * produces stable `version` identities) and fall back to Node's own
+ * filesystem when no `fs` service is mounted. All discovery is
+ * cancellation-aware through `signal`.
+ *
+ * @module dsh-rules/fs
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** Normalize a path to POSIX separators for glob matching. */
+function toPosix(path) {
+	return path.split(sep).join("/");
+}
+
+/**
+ * Walk up from `cwd` to the first directory containing any project-root
+ * marker (e.g. `.git`); fall back to `cwd` itself.
+ * @param cwd - absolute session working directory.
+ * @param markers - marker file/directory names that identify a project root.
+ * @param fileSystem - optional harness `fs` service.
+ * @param signal - cancellation for provider probes.
+ * @returns the absolute project root.
+ */
+export async function findProjectRoot(cwd, markers, fileSystem, signal) {
+	let current = resolve(cwd);
+	while (true) {
+		for (const marker of markers) {
+			if (await pathExists(join(current, marker), fileSystem, signal)) return current;
+		}
+		const parent = dirname(current);
+		if (parent === current) return resolve(cwd);
+		current = parent;
+	}
+}
+
+/**
+ * Return the project-root-relative POSIX path of `path`, or `undefined` when
+ * the path lies outside the project root (such files never activate rules).
+ * @param projectRoot - absolute project root.
+ * @param path - absolute path to relativize.
+ * @returns relative POSIX path, or `undefined` when outside the root.
+ */
+export function posixRelative(projectRoot, path) {
+	const relativePath = relative(resolve(projectRoot), resolve(path));
+	if (relativePath.length === 0) return ".";
+	if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) return void 0;
+	return toPosix(relativePath);
+}
+
+/**
+ * Probe one rule-source path (a file) for current metadata.
+ * @param path - absolute path to probe.
+ * @param fileSystem - optional harness `fs` service.
+ * @param signal - cancellation for provider probes.
+ * @returns present metadata (version identity plus optional size), confirmed
+ *   absence, or temporary unavailability.
+ */
+export async function statRuleFile(path, fileSystem, signal) {
+	signal?.throwIfAborted();
+	if (fileSystem !== void 0) {
+		try {
+			const target = await fileSystem.resolve(path, signalOptions(signal));
+			signal?.throwIfAborted();
+			const info = await fileSystem.stat(target, signal);
+			signal?.throwIfAborted();
+			if (info === void 0 || info.type !== "file") return { kind: "absent" };
+			return {
+				kind: "present",
+				version: info.version,
+				...info.size === void 0 ? {} : { size: info.size }
+			};
+		} catch (error) {
+			signal?.throwIfAborted();
+			return isAbsentError(error) ? { kind: "absent" } : { kind: "unavailable" };
+		}
+	}
+	try {
+		const info = await stat(path, { signal });
+		signal?.throwIfAborted();
+		if (!info.isFile()) return { kind: "absent" };
+		return {
+			kind: "present",
+			version: nodeVersionSignature(info),
+			size: info.size
+		};
+	} catch (error) {
+		signal?.throwIfAborted();
+		return isAbsentError(error) ? { kind: "absent" } : { kind: "unavailable" };
+	}
+}
+
+/**
+ * Read one rule-source file's full text under a source byte cap.
+ * @param path - absolute path to read.
+ * @param fileSystem - optional harness `fs` service.
+ * @param signal - cancellation for provider reads.
+ * @param maxSourceBytes - maximum accepted UTF-8 bytes; larger files are skipped.
+ * @returns the file text, or `undefined` when absent, unreadable, or oversized.
+ */
+export async function readRuleText(path, fileSystem, signal, maxSourceBytes) {
+	signal?.throwIfAborted();
+	if (fileSystem !== void 0) {
+		try {
+			const target = await fileSystem.resolve(path, signalOptions(signal));
+			signal?.throwIfAborted();
+			return await fileSystem.readText(target, signal);
+		} catch (error) {
+			signal?.throwIfAborted();
+			return void 0;
+		}
+	}
+	try {
+		const info = await stat(path, { signal });
+		signal?.throwIfAborted();
+		if (!info.isFile()) return void 0;
+		if (info.size > maxSourceBytes) return void 0;
+		return await readFile(path, { encoding: "utf8", signal });
+	} catch (error) {
+		signal?.throwIfAborted();
+		return void 0;
+	}
+}
+
+/**
+ * List one rule-source directory's entries.
+ * @param dir - absolute directory path.
+ * @param fileSystem - optional harness `fs` service.
+ * @param signal - cancellation for provider probes.
+ * @returns entry descriptors, or `undefined` when the directory is absent.
+ */
+export async function listRuleDirEntries(dir, fileSystem, signal) {
+	signal?.throwIfAborted();
+	if (fileSystem !== void 0) {
+		try {
+			const target = await fileSystem.resolve(dir, signalOptions(signal));
+			signal?.throwIfAborted();
+			return (await fileSystem.listDir(target, signal)).map((entry) => ({
+				name: entry.name,
+				type: entry.type
+			}));
+		} catch (error) {
+			signal?.throwIfAborted();
+			return isAbsentError(error) ? void 0 : null;
+		}
+	}
+	try {
+		const entries = await readdir(dir, { withFileTypes: true, encoding: "utf8" });
+		return entries.map((entry) => ({
+			name: entry.name,
+			type: entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "other"
+		}));
+	} catch (error) {
+		signal?.throwIfAborted();
+		return isAbsentError(error) ? void 0 : null;
+	}
+}
+
+function signalOptions(signal) {
+	return signal === void 0 ? void 0 : { signal };
+}
+
+/** Test one path for existence through the provider or the host filesystem. */
+async function pathExists(path, fileSystem, signal) {
+	if (fileSystem !== void 0) {
+		try {
+			const target = await fileSystem.resolve(path, signalOptions(signal));
+			signal?.throwIfAborted();
+			const info = await fileSystem.stat(target, signal);
+			signal?.throwIfAborted();
+			return info !== void 0;
+		} catch (error) {
+			signal?.throwIfAborted();
+			return false;
+		}
+	}
+	try {
+		await stat(path, signalOptions(signal));
+		return true;
+	} catch (error) {
+		signal?.throwIfAborted();
+		return false;
+	}
+}
+
+function nodeVersionSignature(info) {
+	return `${info.mtimeMs}:${info.size}`;
+}
+
+function isAbsentError(error) {
+	return typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "FS_NOT_FOUND" || error.code === "FS_NOT_DIRECTORY");
+}