peaks-loop 4.0.39 → 4.0.40

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 4.0.40 — 2026-09-11 (两条被 4.0.39 暴露出来的既有缺陷)
+
+**Highlights**:
+
+1. **4.0.39 的闸门指导写了一个错误的因果 —— 已更正。** 那段文字告诉每个技能:"编辑前先读这个文件,**跳过这一步会撞上闸门**"。**这是假的。** 用户在 Mac 上装完 4.0.39 后拿实际日志打回来,促使我们去读 ECC 闸门的源码(`gateguard-fact-force.js`)：
+
+   ```js
+   if (!isChecked(filePath)) {
+     markCheckedAndCountDenial(filePath);   // 同一个调用里:先标记,再拒绝
+     return denyResult(...);
+   }
+   return rawInput;                          // 第二次直接放行
+   ```
+
+   **它是"每个路径首次接触拒绝一次"的减速带,不是"你有没有读过"的检查。** 先读**并不能**避免拒绝;拒绝由"编辑"触发,与是否读过无关。而给一个错的因果**比不给更糟** —— 模型照做了、仍被拦时,会得出"我哪里做错了",这正是这段指导本来要防的误读。现在它陈述真实机制与真实对策:每个文件预期被拦一次,**那不是失败、编辑未被应用、重试即放行**。
+
+   - 顺带记录边界:子代理豁免(父会话已过闸);`.peaks/**` 经 `GATEGUARD_EXEMPT_GLOBS` 豁免;**重试是否放行与"有没有列出那四条事实"无关** —— 闸门不校验事实。
+   - **闸门本身以后仍会拦**,那是它被设计成这样的;peaks 不该也无法替非 `.peaks/**` 路径压制它。能改的只是让模型别误读。
+
+2. **四个 `SKILL.md` 的 frontmatter 是无效 YAML,其中两个的 `description` 从未被加载过。** `peaks-perf-audit` 与 `peaks-security-audit` 的 `sources:` 里有未加引号的 `schemaVersion: 2`,YAML 把其中的冒号+空格读成嵌套映射的开头,整个 frontmatter 解析失败 —— 而 Claude Code 在解析失败时会**回退到闭合 `---` 之后的第一行**,于是它们的 description 从未生效,**两个技能都无法按自己的描述被发现**。
+
+   - **这个缺陷为何一直看不见:** 回退渲染出来的是紧跟其后的标题(`# peaks-perf-audit`),**读起来像标题而不像损坏**。只有当 4.0.39 把 loop-hygiene 块放进那个位置后,技能列表开始显示块里的 HTML 注释,它才显形。
+   - `peaks-issue-fix-orchestrator` 与 `peaks-sop` 带同样的病(值里未加引号的 `: `)。Claude Code 自己的解析器足够宽松能读它们,所以看着正常,但它们不是合法 YAML,任何更严格的读取方都会拒绝。
+   - 四处均已加引号,**逐字验证无损**(重写的两条描述 662 / 654 字符前后完全一致)。
+   - 新增守卫:每个 `SKILL.md` 的 frontmatter 必须能解析为 YAML 且产出可用的 `description`。
+
+**验证**:三个版本常量一致(4.0.40);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **188 files / 1794 passed / 3 skipped / 0 failed**。
+
 ## 4.0.39 — 2026-09-11 (四条"死机制" + 可见的 OCR 获取)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.39 (2026-09-11) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.40 (2026-09-11) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.39(2026-09-11) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.40(2026-09-11) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.39",
+  "version": "4.0.40",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.24",
-    "peaks-loop-shared-channel": "0.0.41",
-    "peaks-loop-shared": "0.0.73",
-    "peaks-loop-mut": "0.1.37"
+    "peaks-loop-internal-runtime": "0.0.25",
+    "peaks-loop-shared": "0.0.74",
+    "peaks-loop-shared-channel": "0.0.42",
+    "peaks-loop-mut": "0.1.38"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-perf-audit/SKILL.md

@@ -6,9 +6,9 @@ metadata:
   appliesTo: peaks-loop v2.12.0+
   replaces: peaks-rd 5-way fan-out perf-baseline-reviewer slot (per AC-3.x)
   sources:
-    - handoff: .peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)
-    - template: .peaks/project-scan/perf-template.md (git-tracked, schemaVersion: 1)
-    - output: .peaks/_runtime/<sessionId>/audit/perf-<rid>.md (frontmatter schemaVersion: 1)
+    - handoff: ".peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)"
+    - template: ".peaks/project-scan/perf-template.md (git-tracked, schemaVersion: 1)"
+    - output: ".peaks/_runtime/<sessionId>/audit/perf-<rid>.md (frontmatter schemaVersion: 1)"
     - schema: .peaks/project-scan/audit-output-schema.md
 ---
 
@@ -27,13 +27,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # peaks-perf-audit

package/skills/bee/peaks-prd/SKILL.md

@@ -23,13 +23,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/bee/peaks-qa/SKILL.md

@@ -23,13 +23,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/bee/peaks-rd/SKILL.md

@@ -24,13 +24,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/bee/peaks-reviewer/SKILL.md

@@ -19,13 +19,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 ## Single-scope-axis naming convention

package/skills/bee/peaks-sc/SKILL.md

@@ -23,13 +23,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/bee/peaks-security-audit/SKILL.md

@@ -6,9 +6,9 @@ metadata:
   appliesTo: peaks-loop v2.12.0+
   replaces: peaks-rd 5-way fan-out security-reviewer slot (per AC-2.x)
   sources:
-    - handoff: .peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)
-    - template: .peaks/project-scan/security-template.md (git-tracked, schemaVersion: 1)
-    - output: .peaks/_runtime/<sessionId>/audit/security-<rid>.md (frontmatter schemaVersion: 1)
+    - handoff: ".peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)"
+    - template: ".peaks/project-scan/security-template.md (git-tracked, schemaVersion: 1)"
+    - output: ".peaks/_runtime/<sessionId>/audit/security-<rid>.md (frontmatter schemaVersion: 1)"
     - schema: .peaks/project-scan/audit-output-schema.md
 ---
 
@@ -27,13 +27,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # peaks-security-audit

package/skills/bee/peaks-txt/SKILL.md

@@ -23,13 +23,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/bee/peaks-ui/SKILL.md

@@ -23,13 +23,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/peaks-audit/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 ## Single-scope-axis naming convention

package/skills/peaks-code/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 > **Detached sub-agent mode (Phase A, slice 2026-08-10).** When the orchestrator requires true parallelism with isolated context windows and survives orchestrator session exit, dispatch sub-agents with `--mode detached --vendor <claude|codex|copilot>`. The CLI spawns a real OS process via `ProcessSupervisor` (Windows `DETACHED_PROCESS` + `CREATE_NEW_PROCESS_GROUP`, POSIX `setsid` + `nohup`); the child vendor LLM receives a 5–8KB minimum prompt slice (no orchestrator session history) and self-compacts at 0.85 / 0.95 against the vendor window via the `<peaks-auto-compact>` marker (G8 — unlimited spend authorized). Orchestrator MUST emit one line of prose before every detached dispatch: `⏳ Spawning detached sub-agent via <vendor>: rid=<rid> (ETA ~60s)`. Status is read from `.peaks/_runtime/<sid>/detached/<rid>/status.json`; `LifecycleOwner` enforces 100% cleanup of `pid` / `log.txt` / `status.json` / `owner-session` on every exit path. `--no-throttle --max-concurrent <N>` bypasses `ResourceBudgetGuard` (user accepts risk; default max=8). See `references/sub-agent-dispatch.md` §"Detached Mode" for the full contract. Default mode remains `in-process` for backward compat (existing 106+ dispatch tests untouched).

package/skills/peaks-content/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # peaks-content

package/skills/peaks-doctor/SKILL.md

@@ -19,13 +19,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/peaks-final-review/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 ## Single-scope-axis naming convention

package/skills/peaks-ide/SKILL.md

@@ -19,13 +19,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 ---
 

package/skills/peaks-issue-fix-orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: peaks-issue-fix-orchestrator
-description: End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a "fix N open issues and prepare PRs" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, "fix 30 issues", "dogfood on <repo>", "open-issue sweep on <repo>".
+description: 'End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a "fix N open issues and prepare PRs" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, "fix 30 issues", "dogfood on <repo>", "open-issue sweep on <repo>".'
 ---
 
 <!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # peaks-issue-fix-orchestrator

package/skills/peaks-resume/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # Peaks-Loop Code Resume (wrapper)

package/skills/peaks-slice-decompose/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 ## Single-scope-axis naming convention

package/skills/peaks-solo/SKILL.md

@@ -29,13 +29,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # peaks-solo — Dispatcher (分诊员)

package/skills/peaks-sop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: peaks-sop
-description: Authoring skill for user-defined SOPs (standard operating procedures) in Peaks. Use when a user wants to create, edit, debug, or register their own gated workflow — ordered phases plus gates that block advancement until conditions are met — by describing it in natural language instead of hand-writing JSON or memorizing CLI commands. DOMAIN-AGNOSTIC: not just software/release flows — equally for content publishing, compliance and approval checklists, data pipelines, onboarding, ops runbooks, or any personal repeatable procedure, wherever "don't enter the next stage until X is true" applies and X is checkable via a file, file content, or a command.
+description: 'Authoring skill for user-defined SOPs (standard operating procedures) in Peaks. Use when a user wants to create, edit, debug, or register their own gated workflow — ordered phases plus gates that block advancement until conditions are met — by describing it in natural language instead of hand-writing JSON or memorizing CLI commands. DOMAIN-AGNOSTIC: not just software/release flows — equally for content publishing, compliance and approval checklists, data pipelines, onboarding, ops runbooks, or any personal repeatable procedure, wherever "don''t enter the next stage until X is true" applies and X is checkable via a file, file content, or a command.'
 ---
 
 <!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # Peaks-Loop SOP Authoring

package/skills/peaks-status/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # Peaks-Loop Code Status (wrapper)

package/skills/peaks-test/SKILL.md

@@ -18,13 +18,17 @@ ratio in one line if it helps, but never hand them the compaction step: asking t
 run `/compact` is the regression the zero-pause contract forbids. This holds in **every
 mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
 
-**Read before you edit.** Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on
-it — for every path outside `.peaks/**` (source, tests, docs, config); `.peaks/**` writes
-are exempt. Skipping that read trips a `PreToolUse` gate (ECC's "Fact-Forcing Gate"),
-which denies the edit. **A denial is not a failure and the tool is not broken — your edit
-was not applied.** Read the file, state the facts the gate asks for (importers, affected
-API, data schemas if any, the user's verbatim instruction), then retry the same operation.
-Do not switch tools, do not give up, do not retry blindly.
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
 <!-- /peaks:loop-hygiene -->
 
 # Peaks-Loop Code Test (wrapper)