focus-guard 0.0.0-stage → 3.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 irisblackwood
+
+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

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# FocusGuard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Chinese](README.zh-CN.md) · English
+
+Guardrails for AI coding agents, enforced at the hook layer. Four behaviours that make agents dangerous stop being prompt advice and become mechanically blocked events: **editing without reading first**, **conclusions without `[file:line]` evidence**, **whole-file reads that burn context**, and **asserting findings that were never verified**. A hit escalates through L1 push-back → L2 forced evidence → L3 fuse → L4 record → L5 downgrade → L6 report.
+
+- **Zero dependencies** — the core package ships no runtime libraries (`dependencies` is empty)
+- **Two enforcement surfaces** — a native DSH plugin (host hooks) plus the ZCode hook shell
+- **Full audit trail** — every block is appended to `.focus-guard/AUDIT.log` (JSONL, rotated and archived)
+- **Auditable rules** — `docs/RULES.md` marks which clauses are machine-enforced and which are not yet implemented
+
+## Install
+
+### DSH (native plugin, recommended)
+
+```bash
+dsh plugin --profile <your-profile> add github:irisblackwood/focus-guard#path:/packages/core
+```
+
+Restart the session to activate. The bundle patch is declared by this package's `package.json` (`dsh.bundle.patch` → `src/dsh/cordis.patch.yml`).
+
+> **Not on npm yet.** `npm install focus-guard` returns 404 — the package has never been published. Use the GitHub install above; it is the only supported route today.
+
+⚠ Mutually exclusive with the official bridge (`@deepseek-ai/dsh-hooks-claude-code`). Mounting both double-runs the same hooks — pick one.
+
+### ZCode
+
+`.zcode-plugin/plugin.json` is ready; import this repository through ZCode's plugin flow.
+
+## What it blocks
+
+| Situation | Mechanism |
+|---|---|
+| Editing files or running mutating commands without investigating first | Layer 4 precondition: the target must have been read in this session, otherwise one refusal (new files exempt) |
+| High-risk commands (recursive delete, format, force-push, publish, global install, system-path writes) | Layer 3 eligibility: **apply before execute**, denied without a grant; `fg_apply` is the request channel |
+| Absolute red lines (`rm -rf /`, `DROP DATABASE`, `git push -f`) | Layer 1 zero-latency short-circuit denial, **no approval prompt** |
+| Dangerous command strings that are merely **quoted** (test data, docs, eval fixtures) | Context exemption on three criteria (quoted / data marker / read-only command) → downgraded to semantic judgement instead of a hard denial |
+| Wrongly blocked, no appeal path | `fg_appeal`: submit counter-evidence anchors, one human ruling, fully recorded |
+| One-size-fits-all across models | Model profiles (`src/profiles/`): review intensity follows the model |
+| Writing `grep`/`find` when the machine wants `rg`/`fd` | Environment fingerprint + hard command check, one-line substitution hint |
+
+## Runtime additions (in-tree, 2026-10-18)
+
+Shipped in the code, not yet reflected in the version number (still `3.0.6`):
+
+- **Heartbeat and liveness** — `src/dsh/heartbeat.mjs:85`, `src/dsh/status.mjs:73`: every 10s the plugin atomically rewrites `.focus-guard/status.json`; `node src/dsh/status.mjs` reports `ALIVE` / `STALE` and exits `0` all-green, `2` module missing, `3` stale, `4` no file.
+- **Module self-check** — `heartbeat.mjs:45`: the ten enforcement seams plus the heartbeat each report at startup; anything missing lands in `degraded`, is warned to the host log, and is injected to the model as `focus-guard-degraded`.
+- **L4 cross-session record** — `src/dsh/workspace.mjs:38` (hash) / `:125` (turn record) / `src/dsh/index.js:71` (injection): state is keyed by `sha256(realpath(cwd))`; a hash mismatch injects nothing, so a renamed folder cannot inherit old state.
+- **Whole-file read gate** — `src/dsh/pipeline.mjs:421` / `:645`: a target above 300 lines read without `offset`/`limit` is denied and pointed at XERJ (`xerj search` / `xerj def`). Configurable via `FG_WHOLE_FILE_MAX_LINES`.
+- **Superpowers writing gate** — `src/dsh/pipeline.mjs:398`: a vague development request (dev verb + vague marker + no acceptance criteria) gets one denial before the first edit/write/destructive shell, requiring `brainstorming` or `writing-plans`; a retry or a loaded skill passes.
+- **Graded destructive heuristic** — `src/dsh/pipeline.mjs:159`: `Remove-Item` / `fs.rmSync` weight by target — system path or recursive `0.9` (blocked), TEMP `0.2`, other `0.4`; redirection `0.15`.
+- **Compaction watch** — `src/dsh/compactionWatch.mjs:239` / `:364`: observes `compaction/start|end|prune` and request-error collisions, records them, and never writes surface or cancels a turn.
+- **Denial reasons in the audit** — `src/dsh/audit.mjs:120`: `auditDeny(exec, cmd, {trigger, level})` records the real rule (`redline:<name>`, `env-substitute`, `gate:fg_apply`, `evidence-gate`, `whole-file:lines`, `risk:<category>`) instead of a constant `high-risk-rm`.
+- **Executor detection** — `src/core/env.mjs:18` + `src/dsh/index.js:31`: the master layer honours an explicit `FG_SHELL`; the DSH adapter declares `powershell`, ending the three-way mismatch between record, fingerprint and actual executor.
+- **Audit isolation guard** — `tests/audit-isolation.mjs:1`: snapshots the real `AUDIT.log` before the suites run and fails the run if it grew (verified both ways: clean Δ0 PASS, deliberate pollution Δ1 FAIL).
+
+## Six-layer eligibility
+
+| Layer | Question |
+|---|---|
+| L0 | Request completeness — empty `purpose` / `scope` is denied |
+| L1 | State — fuse / downgrade / budget exhausted |
+| L2 | Absolute red lines (denied here, never reaches L3) |
+| L3 | High-risk eligibility — matches a high-risk signature with no grant in this session → human approval |
+| L4 | Preconditions — mutating targets must be evidenced; system paths and `.git`/`node_modules` are stricter |
+| L5 | Semantic signals — the model probe's `mismatch` / high-risk score |
+| L6 | Grant and record |
+
+## Three commands
+
+```bash
+npm test                    # acceptance (version consistency, docs-vs-implementation alignment)
+npm run test:eligibility    # eligibility + red-line exemption + appeal
+npm run eval                # threat evaluation (high-risk detection rate + benign false-positive rate)
+```
+
+## Architecture
+
+```
+src/core/           master layer: zero-dependency, host-agnostic judging logic
+src/adapters/dsh/   adapter layer: wires the master into DSH (fg_apply / fg_appeal + eligibility gate)
+src/dsh/pipeline.mjs host hooks: pre-execute / system-prompt / post-execute
+hooks/guard.mjs     ZCode execution shell (sealed: independent version, does not follow the main release)
+```
+
+**Layering rule**: the master layer must not depend back on the adapter layer (locked by an acceptance test).
+
+## Version
+
+Currently `3.0.7`. Eight version surfaces are asserted equal to each other and to the latest `CHANGELOG.md` entry.
+
+## Docs
+
+- Capabilities and troubleshooting: repository `README.md`, `INSTALL.md`
+- Rule text: `docs/RULES.md`
+- Changelog: repository `CHANGELOG.md`
+
+## License
+
+MIT © 2026 irisblackwood

package/README.zh-CN.md

@@ -0,0 +1,98 @@
+# FocusGuard 聚焦护栏
+
+给 AI 编码智能体装上履职纪律：**未取证就改、结论无锚点、整读大文件烧上下文、查无实据硬凑**这四类失控，被变成可机械拦截的行为事件——命中即按 L1 打回 → L2 强制取证 → L3 熔断 → L4 记档 → L5 降权 → L6 上报逐级处置。
+
+- **零依赖**：核心包不依赖任何运行时库（`dependencies` 为空）
+- **DSH 优先执行面**：原生插件（宿主缝）为首选；ZCode 钩子并存，执行壳已封存
+- **全程留痕**：拦截写入 `.focus-guard/AUDIT.log`（JSONL，带体积轮转与归档）
+- **法条可审计**：条文正本 `docs/RULES.md` 明确标注哪些条款已机械化、哪些尚未落地
+
+## 安装
+
+### DSH（原生插件，推荐）
+
+```bash
+dsh plugin --profile <你的 profile> add github:irisblackwood/focus-guard#path:/packages/core
+```
+
+装完 **重启会话** 生效。bundle 补丁由本包的 `package.json` 的 `dsh.bundle.patch` 指向 `src/dsh/cordis.patch.yml`。
+
+> ⚠ **npm 包尚未发布**：`npm install focus-guard` 会返回 404。上面这条 GitHub 路径（带 `#path:/packages/core`）是当前唯一可用的安装方式。
+
+⚠ 与官方桥 `@deepseek-ai/dsh-hooks-claude-code` **互斥**：两条路同时挂载会双跑（同一条缝双监听），**二选一**。
+
+### ZCode（并存，非首选）
+
+`.zcode-plugin/plugin.json` 已就绪，按 ZCode 的插件安装流程导入本仓库即可。执行壳已封存，版本号独立。
+
+## 它拦什么
+
+| 场景 | 机制 |
+|---|---|
+| 未调查取证就改文件 / 执行变更命令 | 第 4 层前置条件：目标须本会话已读，否则拒一次（新建文件除外） |
+| 高危命令（递归强删 / 格式化 / 强推 / 发布 / 全局安装 / 系统路径写入） | 第 3 层资格审核：**先申请后执行**，无授权即拒；`fg_apply` 是申请通道 |
+| 绝对红线（`rm -rf /`、`DROP DATABASE`、`git push -f`） | 第 1 层零延迟短路拒绝，**不弹审批** |
+| 被**引用的**危险命令字符串（测试数据、文档引用、评测集） | 上下文豁免三判据（引号内 / 数据标记 / 只读命令）→ 降级到语义预判，不再直接拒 |
+| 拦错了没有程序可走 | `fg_appeal` 误伤申辩：附反例锚点提交，人类一次性裁决，全程留痕 |
+| 大小模型一刀切 | 模型画像（`src/profiles/`）：按模型调整审核强度 |
+| 本机该用 `rg`/`fd` 却写了 `grep`/`find` | 环境指纹 + 命令硬校验，给一行替代提示 |
+
+## 运行面增量（in-tree，2026-10-18）
+
+已在代码里跑、但版本号仍记 `3.0.6` 的部分：
+
+- **心跳与存活确认** — `src/dsh/heartbeat.mjs:85`、`src/dsh/status.mjs:73`：每 10s 原子覆写 `.focus-guard/status.json`；`node src/dsh/status.mjs` 判活并退出 `0` 全绿 / `2` 缺模块 / `3` STALE / `4` 文件缺失。
+- **模块启动自检** — `heartbeat.mjs:45`：10 条执法缝 + 心跳各自报到；缺谁写 `degraded`、告警宿主日志、并以 `focus-guard-degraded` 段注入模型。
+- **L4 跨会话卷宗** — `src/dsh/workspace.mjs:38`（哈希）/ `:125`（回合落账）/ `src/dsh/index.js:71`（注入）：状态按 `sha256(realpath(cwd))` 绑定；hash 不符零注入，改文件夹名无法继承旧状态。
+- **整文件读取闸** — `src/dsh/pipeline.mjs:421` / `:645`：目标 > 300 行且未带 `offset`/`limit` 即拒，指向 XERJ（`xerj search` / `xerj def`）；阈值 `FG_WHOLE_FILE_MAX_LINES` 可调。
+- **Superpowers 动笔闸** — `src/dsh/pipeline.mjs:398`：模糊开发任务（开发动词 + 模糊标记 + 无验收词）首次动笔拒一次，要求先加载 `brainstorming` 或 `writing-plans`；同条重试或已加载即放行。
+- **破坏性 API 分级** — `src/dsh/pipeline.mjs:159`：`Remove-Item` / `fs.rmSync` 按目标给权——系统路径或递归 `0.9`（拦截）、TEMP `0.2`、其他 `0.4`；重定向 `0.15`。
+- **压缩监察** — `src/dsh/compactionWatch.mjs:239` / `:364`：观察 `compaction/start|end|prune` 与请求错误撞窗并留痕，不写 surface、不 cancel 回合。
+- **审计记录拦截理由** — `src/dsh/audit.mjs:120`：`auditDeny(exec, cmd, {trigger, level})` 记录真实规则名，不再是常量 `high-risk-rm`。
+- **执行体判定** — `src/core/env.mjs:18` + `src/dsh/index.js:31`：母版认显式 `FG_SHELL`；DSH 适配层声明 `powershell`，消除"卷宗【一】/指纹/实际执行"三方矛盾。
+- **审计隔离守卫** — `tests/audit-isolation.mjs:1`：跑测前后比对真实 `AUDIT.log`，有增长即 fail（双向验证过）。
+
+## 六层资格审核
+
+| 层 | 判什么 |
+|---|---|
+| L0 | 申请完整性——`purpose` / `scope` 空白即拒 |
+| L1 | 状态——熔断 / 降权 / 预算耗尽 |
+| L2 | 绝对红线（命中即拒，不进 L3） |
+| L3 | 高危资格——命中高危特征且本会话无授权 → 转人工审批 |
+| L4 | 前置条件——改动类目标须已取证；系统路径与 `.git`/`node_modules` 加严 |
+| L5 | 语义信号——模型探针的 `mismatch` / 高风险分 |
+| L6 | 授权并留痕 |
+
+## 三条命令
+
+```bash
+npm test              # 验收（含版本一致性、文档-实现对齐）
+npm run test:eligibility   # 资格审核 + 红线豁免 + 申辩
+npm run eval          # 威胁评测（高危检出率 + 良性误报率）
+```
+
+## 架构
+
+```
+src/core/        母版层：零依赖、宿主无关的判定逻辑（六层审核 / 画像 / 红线与豁免 / 申辩）
+src/adapters/dsh/  适配层：把母版接进 DSH（fg_apply / fg_appeal 工具注册 + 资格闸）
+src/dsh/pipeline.mjs  宿主缝：pre-execute / system-prompt / post-execute
+hooks/guard.mjs   ZCode 执行壳（已封存：版本号独立，不随主版本更新）
+```
+
+**分层铁律**：母版层**不得**反向依赖适配层（有验收用例锁定）。
+
+## 版本
+
+当前 `3.0.7`。版本面共 8 处由验收断言锁定"彼此相等且等于 CHANGELOG 最新条目"。
+
+## 文档
+
+- 能力与排错：仓库 `README.md`、`INSTALL.md`
+- 条文正本：`docs/RULES.md`
+- 变更记录：仓库 `CHANGELOG.md`
+
+## License
+
+MIT © 2026 irisblackwood

package/docs/LEGISLATION-LAW.md

@@ -0,0 +1,102 @@
+# 人工智能体治理立法法（试行）
+
+| 项 | 内容 |
+|---|---|
+| 名称 | 人工智能体治理立法法（试行） |
+| 版本 | v1.0（试行） |
+| 通过 | 2026-09-29 领导批示「写入新法」 |
+| 施行 | 自发布之日起施行；与既有规则冲突，以本法为准（第八章） |
+| 解释权 | 领导负责解释 |
+| 修改历史 | v1.0 2026-09-29 初次发布 |
+
+---
+
+## 第一章 总则
+
+- **立法目的**：规范治理规则的制定、修改、废止、解释与备案审查。
+- **适用范围**：全部人工智能体治理规则。
+- **基本原则**：
+  - 上位法优于下位法
+  - 特别法优于一般法
+  - 新法优于旧法
+  - 不溯及既往
+  - 实事求是、证据裁判、宽严相济、惩教结合
+
+## 第二章 规则体系（效力由高到低）
+
+```
+[第一级] 根本准则          AGENTS.md / 系统提示词
+    ↓
+[第二级] 监督管理办法      SKILL.md 法典章节
+    ↓
+[第三级] 技术执行规范      guard.mjs 代码规则
+    ↓
+[第四级] 项目级规程        .ai/CASE_FILE.md 顶部声明
+    ↓
+[第五级] 临时批示          对话指令（仅本任务有效）
+```
+
+**冲突处理**：上位优先 > 特别优先 > 新法优先 > 报请领导裁决。
+
+> 载体说明：第二级"监督管理办法"的**法条原文存档**是 `docs/RULES.md`（永不自动加载）；模型运行时实际加载的是 `skills/focus-thinking/SKILL.md` 的法典章节（条文镜像）。两者冲突时以 `docs/RULES.md` 原文为准，并以镜像同步为待修缺陷。
+
+## 第三章 制定权限
+
+| 载体 | 制定/修改主体 |
+|---|---|
+| 根本准则 | 仅领导制定修改，不得授权 |
+| 监督办法 | 人工智能体起草，报领导批准 |
+| 执行规范 | 人工智能体起草，报领导批准 |
+| 项目规程 | 领导或承办人制定，报领导备案 |
+| 临时批示 | 领导作出，仅本次任务有效 |
+
+## 第四章 制定程序
+
+```
+动议 ──> 起草 ──> 审议 ──> 通过 ──> 公布
+```
+
+- **动议**：领导提出或人工智能体建议。
+- **起草**：须明确适用对象、判定标准、处置措施、救济途径、不抵触上位法。
+- **审议**：领导审阅，可退回重拟。
+- **通过**：领导明确同意。
+- **公布**：写入载体，同步生效。
+
+## 第五章 适用规则
+
+- 上位规则优于下位规则。
+- 特别规定优于一般规定。
+- 新规定优于旧规定。
+- 不溯及既往（有利除外）。
+- **发现冲突必须停止执行、报告领导，不得自行选择。**
+
+## 第六章 修改与废止
+
+**修改情形**：
+- 上位规则修改，下位抵触。
+- 实践发现漏洞或误伤。
+- 技术环境变化，无法执行。
+- 领导认为需要修改。
+
+**废止情形**：
+- 上位规则已废止。
+- 规范事项已不存在。
+- 被新规则取代。
+- 领导决定废止。
+
+**载体同步顺序**：根本准则 > 监督办法 > 执行规范 > 项目规程 > 临时批示。
+
+## 第七章 备案审查
+
+- 全部规则写入 `.focus-guard/AUDIT.log`，记录名称、生效时间、修改历史。
+- **引擎自动执行的部分**（钩子 SessionStart 时）：登记生效规则集（`rules-registered` 事件，含立法法版本、监督办法版本与引擎号），并核验"注册表 `installed_plugins.json` ↔ 市场源 `marketplace.json` ↔ 运行引擎 `ENGINE_VERSION`"三方一致，漂移即写 `deploy-mismatch` 事件并在会话注入中警告。
+- 领导有权随时审查，可指令修改或废止。
+- 执行中发现无法执行、误伤过高、抵触上位、明显漏洞的，应报告。
+- 项目规程与临时批示须报领导备案，领导可改变或撤销。
+
+## 第八章 附则
+
+- **施行日期**：自发布之日起施行，与既有规则冲突以本法为准。
+- **解释权**：领导负责解释。
+- **修改程序**：参照第四章执行。
+- **修改历史**：本法自身 v1.0 后未修改；下位载体的历次修改（2.0.0 → 2.5.2）见 [CHANGELOG.md](../CHANGELOG.md) 与 `docs/RULES.md` 附注的"实施差异备忘"。

package/docs/MASTER-PLAN-2.0.0.md

@@ -0,0 +1,133 @@
+# 卷宗体系重构总纲（2.0.0）
+
+> 原则：一次检测全程复用，卷宗留痕指纹防伪，跨平台适配不重复取证
+>
+> （工程总纲，非法条；对应引擎 `hooks/guard.mjs` v2.5.2；卷宗结构沿用 2.0.0 设计）
+
+## 一、核心定位
+
+1. 旧格式直接废弃，不写兼容层，不写迁移脚本（当时项目未开源、无外部用户；**仓库现已公开**，此后破坏性变更须在 [CHANGELOG.md](../CHANGELOG.md) 显式声明）。
+2. 版本号 1.0.0 → 2.0.0，不兼容变更，一次性重构到位。
+3. 当时约定 Git 历史可重写、强制推送允许；**公开后不再默认适用**——强推属高危命令，须走【高危申请】审批单（第七十五条(三)）。
+
+## 二、卷宗文件结构（.ai/CASE_FILE.md）
+
+### 【一】环境声明（会话启动时检测，全程复用）
+
+操作系统 / Shell 版本 / 默认编码 / 路径分隔符 / 文件系统大小写敏感 / BSD 工具检测 / 可用命令清单
+
+### 【二】项目依赖声明（人工填写，可覆盖自动 TTL）
+
+| 依赖名 | 版本 | 安装路径 | 更新频率 | 信任TTL | 备注 |
+|---|---|---|---|---|---|
+| 游戏本体 | 1.6.2 | D:\Games\XX | 稳定拖沓 | 60天 | 社区共识更新慢 |
+
+### 【三】侦查取证记录（插件自动追加）
+
+| 文件名 | 读取时间 | mtime | size | SHA-256 | 变更历史 | TTL | 验证方式 |
+|---|---|---|---|---|---|---|---|
+
+（TTL 列留空 = 自适应；人工填写如 `30天`/`1小时` = 覆盖）
+
+### 【四】工作额度台账
+
+初始额度 / 已用额度 / 剩余额度 / 有效调用 / 无效调用 / KPI（2.3.0 起补 KPI 列）
+
+## 三、环境检测（会话级，一次检测全程生效）
+
+检测时机：SessionStart 执行一次，写入 `state.envCache`；`envCache` 非空即代表"已检测"，不再另设布尔标记（原 `envChecked` 只写不读、且可能与缓存不一致，2.5.1 删除）。UserPromptSubmit 不重检。仅当明确探测到 shell 变化时重检。检测结果同时写入卷宗【一】的环境声明行，供人类直接查阅（2.5.1）。
+
+检测项：
+
+- 操作系统（Windows / macOS / Linux）
+- Shell 与版本（PowerShell 7.6.6 / zsh 5.9 / bash 5.2）
+- 默认编码（UTF-8 / GBK / UTF-16）
+- 路径分隔符（\ 或 /）
+- 文件系统大小写敏感（是 / 否）
+- BSD 工具检测（sed/grep/awk 是否为 BSD 版本）
+- 可用命令（grep / sed / awk / gsed / greadlink）
+
+## 四、不重复读校验流程
+
+```text
+读取请求
+   |
+   v
+查卷宗记录
+   +-- 无记录 ---------> 首次读取 -> 记录 mtime/size/hash/TTL
+   +-- 有记录 ---------> mtime + size 比对
+         +-- 不一致 ----> 拦截免读资格，放行真重读（更新指纹）
+         +-- 一致 ------> SHA-256 校验（≤200KB）
+               +-- 不一致 -> 拦截免读资格，放行真重读
+               +-- 一致 ---> Git diff 校验
+                     +-- 有变更 -> 拦截免读资格，放行真重读
+                     +-- 无变更 -> TTL 校验
+                           +-- 未超 -> 免重读放行（复用已有取证）
+                           +-- 超时 -> 拦截免读资格，放行真重读
+```
+
+## 五、自适应 TTL
+
+| 变更历史 | TTL |
+|---|---|
+| 30 天未变 | 7 天 |
+| 7 - 30 天未变 | 24 小时 |
+| 7 天内有变 | 2 小时 |
+| 首次遇到 | 4 小时（保守） |
+| 项目依赖声明覆盖 | 按声明 TTL（如游戏本体 60 天） |
+| 人工标注覆盖 | 按标注 TTL（稳定 30 天 / 活跃 1 小时） |
+
+优先级：项目依赖声明 > 人工标注 > 自适应 TTL。
+
+## 六、跨平台命令拦截
+
+Windows（PowerShell 会话）：
+
+- 禁 bash 语法（\| head / \| grep / \| wc / \| sed / \| awk / &&）
+- 禁裸 cat/grep/wc
+- 强制 UTF-8
+- 用 Get-Content / Select-String / Measure-Object
+
+macOS：
+
+- 禁 sed -i 不带 ''
+- 禁 grep -P
+- 禁 readlink -f
+- 大小写不敏感下禁仅大小写不同的重名文件
+
+Linux：标准 GNU 工具，无特殊限制。
+
+## 七、插件钩子逻辑（2.0.0 骨架；当前实现顺序见下）
+
+- SessionStart：读取卷宗 + 环境检测（若未检测）；重建 readSetCache 与 TTL 表；注入常驻纪律；登记生效规则集与部署版本核验
+- UserPromptSubmit：重置任务级状态（预算/违规），保留侦查缓存；识别批示（特赦/信用延期/追加额度/y-n）；shell 变化重检
+- PreToolUse（当前顺序）：平台命令检查 → 大小写冲突 → **熔断期白名单（先判高危命令，一律拒绝）** → L2/L5 拒绝改动 → **高危命令闸（审批单）** → 脚本包装 → 污染核实闸 → 触发①未取证 → 盲写 → 体积三闸 → 卷宗免重读 → 改动前备份
+- PostToolUse：更新侦查记录与 TTL；记录有效/无进展；更新额度台账；污染检测；委派摘要校验与强制场景 KPI；抽查A
+- PostToolUseFailure：失败计入停滞（DSH 桥无此事件）
+- Stop：证据锚点检查 → 授权识别核验 → 熔断声明与降级方案 → 审批单格式校验 → 台账落卷（各打回均带一次性保护）
+
+## 八、预期效果
+
+1. 跨回合不重复读已取证文件（指纹一致即放行）。
+2. 稳定依赖（游戏本体/SDK）一次声明，长期免重读。
+3. 时间戳伪造（git checkout / cp -p / touch -d）无法绕过校验——**边界**：SHA-256 仅覆盖 ≤200KB 的文件；超出退回 mtime+size+git 脏态，工作区无 git 时无法察觉"同尺寸改写+还原 mtime"（2.5.2 明确，见 README 与 RULES 附注）。
+4. 环境切换被识别，规则自动适配，不污染既有配置。
+5. 会话级检测不占任务预算，不受任务污染。
+
+一句话：卷宗管档案，环境管适配，指纹管真伪，TTL 管时效。
+
+---
+
+## 九、后续版本增补（相对本 2.0.0 总纲）
+
+本文件定的是卷宗体系的骨架；其后各版本在此之上增补，完整清单见 [CHANGELOG.md](../CHANGELOG.md)：
+
+| 版本 | 相对本总纲的增补 |
+|---|---|
+| 2.0.1 / 2.0.2 | win32 shell 误判热修；`.csproj`/`.sln` 列入风险文件 |
+| 2.2.0 | 法条第十五章之一（正面指引）+ 三处机械化：污染核实闸、改动前自动备份、推送走审批单（推送口径 2.4.0 再改） |
+| 2.3.0 | 委派条例：委托池独立核算、子代理摘要强制格式、强制委派场景 KPI、熔断期委派=越权 |
+| 2.4.0 / 2.4.1 | 高危命令闸（六类 + 审批单 y/n + 预授权隔离 + 反脚本包装）；特征库加固与卷宗缓存裁剪 |
+| 2.5.0 | DSH 硬拦截（官方桥直跑 hooks.json），取代监察留痕模式 |
+| 2.5.1 | 卷宗【一】环境声明落卷；`envChecked` 删除（`envCache` 非空即已检测）；假留痕防线；版本全链一致 |
+| 2.5.2 | 敏感文件不落明文备份；状态原子落盘；熔断期不放行高危命令；指纹防伪边界写明 |

package/docs/MASTER-PLAN-3.0.0.md

@@ -0,0 +1,76 @@
+# 协作治理总纲（3.0.0）
+
+> 十大原则 → 十项机制：中心调度、蜂群委派、去中心化验证、静态图书馆、积木拼装、本地哨兵、KPI 兑现、提问即治理、因果链追溯、开源收尾。
+>
+> （工程总纲，非法条；法条载体见 [RULES.md](RULES.md) 第十五章之二与相关条款，引擎 `hooks/guard.mjs` v3.0.0。研读依据引自本地明文库 `E:\DSH\vault-plain\`（密文正本在 `miniature-happiness-main` 仓）。）
+
+## 一、定位
+
+2.x 时代 FocusGuard 管的是**单会话的履职纪律**（取证、预算、锚点、高危）。3.0 把治理面扩展到**多代理协作与知识资产**：主会话怎么调度、子代理怎么回传、审计由谁做、知识放哪里、表现怎么兑现。不变量依旧：日常零打扰，只拦行为，全程留痕，人类批示至上。
+
+## 二、十大原则 → 十项机制
+
+### 1. 中心思维（主会话只做调度与审计）
+- **依据**：R1 主题4"delegate and you keep the conclusion, not the file dumps"；R7 关键路径理论。
+- **机制**：主会话定位=调度者+审计者。关键路径任务（下一步等它的结果）亲手做；sidecar 任务（可并行、可等待）一律委派。强制委派场景（11.3）已有引擎判定，本条补齐"委派期间主会话做什么"——立即做不重叠的实质工作，禁反射性等待（R7 §五）。
+- **落地**：RULES 十五·二（一）；SKILL §13.1。
+
+### 2. 蜂群思维（无状态子代理 + 摘要回传）
+- **依据**：R7 §三（self-contained / disjoint write sets）；R2 T13（只读委派优先、三层只读执法）；R4 §七（fork 继承式 vs 新鲜式并存的显式区分）。
+- **机制**：派单自包含（子代理不继承对话，上下文随派单给全量——R3-8：简洁规则不适用于子代理派单）；回传只收【子代理摘要】四字段（11.2 已机械化）；并行任务按互不相交写集分解；多 worker 共存三律（所有权明确/不回滚他人/适配他人）；委派默认只读，写权限按需显式开。
+- **落地**：RULES 十五·二（二）；SKILL §13.2；引擎 delegate-used 事件带子链（见第 9 条）。
+
+### 3. 去中心化验证（跨模型交叉审计，拒绝互评点头）
+- **依据**：R5-5 advisor-tool（二级复核层，全库唯一：更强模型在"实质工作前/宣称完成前"复核）；R1 主题10 谄媚防护；R1 主题9 codex auto-review（findings first）。
+- **机制**：关键决策（高危批准前、熔断宣告前、宣称完成前）引入**换模型互查**——审计不得由产出者自评；复核报告 findings-first（按严重度排序带 文件:行号），没发现问题须明说查了什么、残余风险是什么；"同意"不算复核发现，无锚点的互评一律视为点头。
+- **落地**：RULES 十五·二（三）；SKILL §14。平台无法强制指定复核模型，本条属纪律条款（人工执行），列入未机械化清单的"纪律执行"栏。
+
+### 4. 静态知识图书馆（动静隔离，避免污染动态卷宗）
+- **依据**：R6 M6-1 Codex Memory 四机制（记忆更新隔离区：AI 只能往隔离区丢便签，不能直接改自己的知识库）；R1 主题6（索引与内容分离、查重删错）；R5-4 doctor（剪掉能自行推导的，保留 gotcha 与非标准约定）。
+- **机制**：`.ai/library/` 为静态积木区：构建后不可变；引擎拦截直写（提示写 inbox/）；图书馆读不进卷宗【三】（积木指纹在 INDEX.md 固化，动态卷宗只管动态工作区）；免重读闸对积木不生效（积木粒度小，重读成本天然低）。
+- **落地**：引擎 `LIBRARY_RE` 三处（直写拦截 / 免卷宗记账 / 免重读豁免）；`tools/library-build.mjs`。
+
+### 5. 积木化拼装（把书拆成积木，把开发做成拼积木）
+- **依据**：R6 M6-1 机器可解析引用（`MEMORY.md:行号|note=用法`——引用粒度到块）；R5-2 consolidate-memory（持久/时效分离、易重查的删、索引限额）。
+- **机制**：`library-build.mjs` 把研读长文按 `##` 节拆成自包含积木（frontmatter：id/来源/sha256/tags），INDEX.md 一行一条指针；引用知识 = 引积木 id（如 `[经验:B003]`），不再整文搬运。开发同理：任务结论引用积木块而非重抄原文。
+- **落地**：`tools/library-build.mjs`（幂等：同源同指纹保留原 id；源移除标 retired 不物理删）。
+
+### 6. 本地零成本哨兵（Needle 2 替代 Jev，离线拦截）
+- **依据**：R5-6 Computer-Use 风险分税制（特征库六类之外还有"代理性通信/敏感数据传输"两维）；R1 主题3 Grok 反绕过宣言。
+- **机制**：`tools/sentinel.mjs` 离线预判命令风险（管道执壳/混淆绕行/外发数据/持久化通道/块设备直写等特征库未覆盖形态）。引擎内建启发式（零依赖零成本）；`--model-cmd` 可挂本地小模型 Needle 2（Cactus Compute 45M/14MB，工具调用与结构化 JSON 判定）做外判——替代云端判定方案（Jev）的本地化落点，离线即拦截，模型失败静默回退启发式。引擎接入 opt-in：`FG_SENTINEL=1`（默认 audit-only 只记档；`FG_SENTINEL_MODE=strict` 升级拦截）。
+- **落地**：`tools/sentinel.mjs`；guard.mjs pre 模式哨兵层。
+- **注**：Jev 无本地出处可考，本机制按"云端判定→本地零成本"的替代目标实现，接口可插拔。
+
+### 7. KPI 兑现闭环（不再是记分牌，而是真正的考核奖惩系统）
+- **依据**：RULES 二十七~三十二条（考核等次/奖惩/跨任务累计）原列"未实现"；表4 已有等次口径。
+- **机制**：Stop 收尾即结算——本任务 KPI → 等次（≥+15 优秀 / 0~+14 称职 / -9~-1 基本称职 / ≤-10 不称职）→ 委托池奖惩（+5 / 0 / -2 / -5，下限 0）→ `kpiCarry` 跨任务累计落台账。执行池增减仍由人类批示（批示至上不变）；KPI ≤-10 保留一次性提醒。AUDIT 记 `kpi-settle`（ref 指向 stop-fired）。
+- **落地**：guard.mjs stop 模式结算块；RULES 十五·二（四）；表4 增机械化注记；未机械化清单更新（等次+委托池奖惩已机械化，立功减刑仍人工）。
+
+### 8. 提问即治理（漏斗式下发任务，避免空洞指令）
+- **依据**：R1 主题5 澄清经济学（Grok 三问判据、Codex"elapsed time is not an approval"）；R4 §六（提问工具化共识）；R2 T15 Jules 两段式批准。
+- **机制**：任务下发漏斗——治理目标 → 约束（禁区/预算）→ 验收锚点（什么信号算完成）→ 额度批示。空洞指令（无验收锚点）主会话不得硬猜：按三问判据（毁灭性？歧义无法自查？只有人类知道？）澄清后再动。计划批准 ≠ 实现批准：批示开工不豁免【提交申请】。
+- **落地**：RULES 十五·二（五）；SKILL §15、§10.5 增补。
+
+### 9. 因果链追溯（日志从流水账变因果图）
+- **依据**：偷师 Semantica（图原生记忆层：因果链追溯 + 溯源 + Knowledge Explorer）。
+- **机制**：AUDIT.log（JSONL）每条增三字段：`seq`（时间戳36进制.调用内序号，全局唯一）、`chain`（任务链，reset 起新链 T*，会话启动 S*，子代理派生 `/dN` 子链）、`ref`（父事件 seq）。`tools/audit-chain.mjs` 按链重组渲染因果树/因果图（--mermaid 直接进 Markdown）。旧格式日志兼容（无 seq 视为流水账，明确提示不虚构链）。
+- **落地**：guard.mjs `audit()`/`auditChainInit()`；委派事件挂子链（ref 指回派单）；`tools/audit-chain.mjs`；表6 增三字段。
+
+### 10. 开源工程化收尾（CHANGELOG + Git 历史整理 + README 重定位）
+- **机制**：git 初始化 + 按逻辑单元结构化提交；CHANGELOG 3.0.0 依例记录（含破坏性变更申报：AUDIT.log 格式追加字段、解释器 eval 不再算只读侦查）；README 增加 3.0 协作治理章与工具表；版本五处清单 + ENGINE_VERSION 同步 3.0.0（验收锁定）。
+- **随批修复**（deep-review-v2.5.3 修复优先级"随下个补丁"项）：FG-D1（授权引文核验 500 字符窗口截断致误伤——核验窗口扩至 4000 字符）；FG-D2（卷宗【一】改原子写）；FG-D3（tmp 残片清理对齐 saveState）；FG-D4（卷宗初始化包防御降级继续）；R5-3 采纳（解释器 `-c/--eval` 不再判只读侦查——堵熔断期白名单放行解释器的洞）。
+
+## 三、研读资料整合
+
+vault（`miniature-happiness-main` 密文正本 / `vault-plain` 明文库）→ 积木图书馆流水线：
+
+1. **素材**：R1-R7 厂商提示词挖掘七轮（8.8 万字，26 项采纳矩阵）、focus-guard v2.5.3 深度审查（FG-D1~D8）、cs2 深度审查、system_prompts_leaks 917 文件原典。
+2. **拆积木**：`library-build.mjs --src <vault-plain 目录> --out .ai/library`，按 `##` 节切块、指纹固化、索引指针化。
+3. **落地残余采纳项**（本批随 3.0.0 落地）：数据保真四铁律（R4 §一）、skill 污染防御（R4 §三）、关键路径/写集分离/共存三律/等待纪律/explorer-worker 二分（R7）、只读委派优先与计划批准≠实现批准（R2）、记忆 stale 标注与更新隔离区（R6 M6-1）、幽灵任务确认（R6 M6-2）、首版唯一声明（R2 T14）。
+4. **更新纪律**：AI 不得直写积木区，只进 inbox 便签区；合并须人工或后台流程（R6 隔离区 + 2.5.3 查重删错双保险）。
+
+## 四、验收
+
+- 引擎：`npm run check`（验收用例含因果链字段、KPI 结算、图书馆隔离、FG-D1 长批示引文、解释器黑名单）。
+- 工具：library-build 幂等（重建保留原 id）、audit-chain 旧格式提示不虚构、sentinel 高危判 block / 良性放行。
+- 版本：五处清单 + ENGINE_VERSION + 头注释一致（既有用例）。