peaks-loop 4.1.13 → 4.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.13"
4
+ "version": "4.1.14"
5
5
  },
6
6
  "plugins": [
7
7
  {
8
8
  "name": "peaks-loop",
9
9
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
10
- "version": "4.1.13",
10
+ "version": "4.1.14",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,70 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.14 — 2026-10-21(门禁按文件判而不是按写法判、发布包在任何 npm 布局下都能启动、门禁判不了时说得出来)
4
+
5
+ **版本级别**: 未发布区间 `v4.1.13..HEAD` 共 **4 个 commit**(**3 fix / 1 docs**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。本次是**纯修复**:既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、peaks-code 的 11 步工序与 Gate A–G **一字不改**。两处行为变化都是本次要修的:**硬阻断路径的绝对写法现在被拒**(原先放行),以及**判不了的 payload 从静默放行变成留下可见标记**。
6
+
7
+ ### 1. 门禁按文件判,不按写法判(`eeb02060`)
8
+
9
+ - 门禁此前用**裸 `startsWith`** 把硬阻断族和 payload 里的路径对起来,**整条门禁路径上没有任何归一化**。
10
+ 族是项目相对前缀(`src/` `tests/unit/` …),于是 `src/x.ts` **被拒**,而 `./src/x.ts` 和**同一个文件的绝对写法被放行** ——
11
+ 同一处编辑,换个写法就过,**而且过的正是那个写法**。门禁自己的测试**只用过相对写法**,另两种从未被执行。
12
+ - 现在:项目根**以内**的绝对路径先变成项目相对形式再匹配,开头的 `./` 去掉,分隔符折成 `/`。
13
+ **项目根之外**的绝对路径保持绝对:这些族名的是**本项目**的目录,别的仓库是别的仓库的事,
14
+ 而且**修之前所有绝对路径本来就放行**,所以这**不是放宽**。
15
+ - `..` 段**故意不解析**:相对路径是相对**工具调用自己的工作目录**的,门禁并不知道那个目录,
16
+ 拿项目根去解析是猜。
17
+ - `.sh` 兄弟脚本只做**拼写层面**的折叠:它不收环境变量也没有参数,**没有项目根**,硬猜会变成误拦;
18
+ 它仍然**不**解析 driver —— 那会是同一个决定的第二个实现。
19
+
20
+ ### 2. 发布包在任何 npm 布局下都能启动(`386ff9d9`)
21
+
22
+ - `peaks-loop-shared` **只发布 `dist/**`**(里面没有 `skills/`),所以它**永远不可能**是"skills 在哪"的答案;
23
+ 旧的查找靠向上找一个**同时有 `package.json` 和 `skills/`** 的目录。
24
+ ⇒ 只有当子包**嵌套在根包之下**时才找得到 —— 而那恰好是 npm **全局**安装的布局,
25
+ 所以 `npm i -g peaks-loop` 一直好用;**本地**安装把子包**提升**到根包旁边,于是发布的 CLI **一 import 就死**:
26
+ `Error: Unable to locate Peaks repository root from .../node_modules/peaks-loop-shared/dist`。
27
+ **README 只写了全局安装**,所以坏掉的正是没写的那条路。
28
+ - 现在:查找在**每一层**都多问一句"根包是不是**在我旁边**",嵌套、提升、pnpm store 三种布局都覆盖;
29
+ 根包根本不在盘上时,回落到**真源资产库**(`PEAKS_HOME` 或 `~/.peaks`)—— skills 的法定居所。
30
+ - 共享包只发布 `dist/**`,**不能** import 根包的脚本,所以那个环境变量名在**两处各写一遍**,
31
+ 并在两处都记下了原因。
32
+
33
+ ### 3. 门禁判不了的时候,说得出话(`8060706e`)
34
+
35
+ - payload 缺失或解析不了时门禁**仍然放行**,这是有意的:payload 送不到时**每次编辑都被拦**比放行更糟。
36
+ 但那个放行**是静默的**,而它藏起来的失败恰是最贵的那种 ——
37
+ 用管道喂 payload 的验收(有些 shell 根本不往进程转发 stdin)会**每个用例都过,却什么都没验**。
38
+ - 现在判不了的那一处在 **stderr 上留下 `PEAKS_CODE_GATE_UNDECIDABLE`**(PreToolUse 的 stderr 本来就喂给 LLM),
39
+ 并把"用**文件重定向**喂 payload"的配方一并写出来。
40
+
41
+ ### 4. 三个残留,**诚实记录**(不是本次的回归)
42
+
43
+ QA 独立复核时把 pre-fix 的源码抽出来实际跑过,确认以下三种写法**修之前也放行**,所以不是本次引入的:
44
+
45
+ | 残留 | 修前 | 修后 | 严重度 |
46
+ |---|---|---|---|
47
+ | `SRC/foo.ts` —— 族名的**大小写变体** | allow | allow | LOW |
48
+ | `docs/../src/foo.ts` —— 相对路径里**没解析的 `..`** | allow | allow | LOW |
49
+ | `.sh` 兄弟脚本 vs Node 命令(绝对硬阻断路径) | 都 allow | shell allow / node **deny** | MEDIUM |
50
+ | 项目**嵌在 git 仓库里** —— 绝对写法按 git 根判 | allow | allow | MEDIUM |
51
+
52
+ ⇒ **"拼写无关"这条不变量,只在「项目根就是 git 根」时成立。** 前两条与刚修的缺陷**同类**
53
+ (大小写不敏感的文件系统上 `SRC/foo.ts` **就是** `src/foo.ts`)。判 LOW 的理由:这道门防的是
54
+ **误操作**,不是敌手。**留待后续决定是否再开一个 slice。**
55
+
56
+ ### 5. 证据
57
+
58
+ - QA **独立复核**(不是采信 RD 的报告):三个变异**自己重推**,结果与 RD 报的**完全一致**
59
+ (归一化关掉 8 红 / 「根包在旁边」关掉 1 红 / 去掉两处 `reportUndecidable` 2 红)。
60
+ - 全量 `pnpm test:unit`:**565 文件 / 6204 通过 / 3 skip / exit 0,零失败**;
61
+ `tsc` 0 错;`node .husky/peaks-gate.mjs repo` 绿且**每个上限未动**(两个 eslint 上限各**降** 1)。
62
+ - 真实环境:5 个打包好的 tarball 装进**仓库之外**的全新目录,**npm 自己的提升布局、没手工挪** ⇒
63
+ `peaks --version` 起得来;**pre-fix** 的查找在同一条路径上**复现**了
64
+ `Unable to locate Peaks repository root`。
65
+ - 拼写矩阵(**文件重定向**喂 payload,绝不走管道):相对 / `./` / Windows 反斜杠 / `.\` / 绝对
66
+ —— **五种写法同一个判定,全部 deny**。
67
+
3
68
  ## 4.1.13 — 2026-10-21(peaks-race-code 批量模式:一次门禁归因、scoped test 前置的修复阶段、上下文监控)
4
69
 
5
70
  **版本级别**: 未发布区间 `v4.1.12..HEAD` 共 **32 个 commit**(**10 feat / 11 fix / 11 docs**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。本次是**纯追加**:新的 `peaks batch` 命令组、新的 `src/services/batch/**` 与 `src/services/lint/**` 模块;既有 CLI 参数、peaks-code 的 11 步工序、Gate A–G 与 transition 状态机**一字不改**。唯一触及既有共享路径的两处 —— `auto-compact-decision.ts` 的可选 `atPhaseBoundary`、`skill-context-verdict.ts` 的可选 `batch` 参数 —— **缺省时行为逐字不变**,对非批量用户无影响。
@@ -21,4 +21,22 @@
21
21
  */
22
22
  import type { Command } from 'commander';
23
23
  import { type ProgramIO } from '../cli-helpers.js';
24
+ /**
25
+ * The marker the gate leaves on stderr when it could not decide.
26
+ *
27
+ * The gate fails OPEN on a payload it cannot read, and that is deliberate: a
28
+ * blocked edit on every call would be worse than an allowed one. But a silent
29
+ * allow is invisible, and the failure it hides is the expensive kind — an
30
+ * acceptance that feeds the payload through a pipe (which some shells do not
31
+ * forward to the process at all) then "passes" every case while proving
32
+ * nothing. So the case says so, on the channel the harness already reads.
33
+ */
34
+ export declare const UNDECIDABLE_MARKER = "PEAKS_CODE_GATE_UNDECIDABLE";
35
+ /**
36
+ * How to feed the payload so that it arrives. A pipeline is not a delivery
37
+ * mechanism on every shell — a PowerShell pipeline to a native executable
38
+ * does not forward stdin at all — and then the gate reads no payload, allows
39
+ * everything, and the check passes vacuously.
40
+ */
41
+ export declare const PAYLOAD_DELIVERY_RECIPE: string;
24
42
  export declare function registerCodeGateCommand(program: Command, io: ProgramIO): void;
@@ -20,7 +20,7 @@
20
20
  * vendor-neutral — no vendor references in the source code itself.
21
21
  */
22
22
  import { addJsonOption, printResult } from '../cli-helpers.js';
23
- import { decideGateAction, extractFilePath } from '../../services/hooks/pre-tool-code-gate.js';
23
+ import { decideGateAction, extractFilePath, isGatedTool } from '../../services/hooks/pre-tool-code-gate.js';
24
24
  import { hasLeaseForCaller, resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
25
25
  import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
26
26
  import { pluckObject, pluckString } from '../../services/ide/hook-translator.js';
@@ -59,6 +59,81 @@ function resolveDriver(projectRoot, payload) {
59
59
  return null;
60
60
  return resolveActiveSkillForCaller(projectRoot, { callerId }).skill;
61
61
  }
62
+ /**
63
+ * The marker the gate leaves on stderr when it could not decide.
64
+ *
65
+ * The gate fails OPEN on a payload it cannot read, and that is deliberate: a
66
+ * blocked edit on every call would be worse than an allowed one. But a silent
67
+ * allow is invisible, and the failure it hides is the expensive kind — an
68
+ * acceptance that feeds the payload through a pipe (which some shells do not
69
+ * forward to the process at all) then "passes" every case while proving
70
+ * nothing. So the case says so, on the channel the harness already reads.
71
+ */
72
+ export const UNDECIDABLE_MARKER = 'PEAKS_CODE_GATE_UNDECIDABLE';
73
+ /**
74
+ * How to feed the payload so that it arrives. A pipeline is not a delivery
75
+ * mechanism on every shell — a PowerShell pipeline to a native executable
76
+ * does not forward stdin at all — and then the gate reads no payload, allows
77
+ * everything, and the check passes vacuously.
78
+ */
79
+ export const PAYLOAD_DELIVERY_RECIPE = 'feed the payload by FILE REDIRECTION (cmd /c "peaks code-gate < payload.json"), not through a pipe: ' +
80
+ 'a shell pipeline does not always forward stdin to the process, and then every case is allowed and the check proves nothing.';
81
+ /** Say, on stderr, that the gate could not decide — and still allow. */
82
+ function reportUndecidable(reason) {
83
+ process.stderr.write(`${UNDECIDABLE_MARKER}: ${reason}; allowing. ${PAYLOAD_DELIVERY_RECIPE}\n`);
84
+ }
85
+ /**
86
+ * The reason this payload cannot be judged, or `null` when it can.
87
+ *
88
+ * A payload that names a gated tool but no target path is the same "cannot
89
+ * decide" the empty payload is: there is no file to match against a family.
90
+ */
91
+ function undecidableReason(tool, input) {
92
+ if (!isGatedTool(tool))
93
+ return null;
94
+ if (extractFilePath(input).length > 0)
95
+ return null;
96
+ return 'the payload names a gated tool but no target path';
97
+ }
98
+ /** The payload as bytes, or `''` when stdin could not be read. */
99
+ async function readPayload() {
100
+ try {
101
+ return await readStdin();
102
+ }
103
+ catch {
104
+ // Empty / unreadable stdin → fail-open allow. The shell-script
105
+ // sibling does the same.
106
+ return '';
107
+ }
108
+ }
109
+ /** The payload as an object, or `null` when it is empty or malformed. */
110
+ function parsePayload(raw) {
111
+ if (raw.trim().length === 0)
112
+ return null;
113
+ let parsed = null;
114
+ try {
115
+ parsed = JSON.parse(raw);
116
+ }
117
+ catch {
118
+ // Malformed JSON → fail-open allow. Cannot decide safely.
119
+ parsed = null;
120
+ }
121
+ return parsed;
122
+ }
123
+ /** The verdict envelope, in the shape the `--dry-run` mode prints. */
124
+ function printDryRunVerdict(io, asJson, context) {
125
+ const { tool, input, verdict, undecidable } = context;
126
+ if (verdict.action === 'allow') {
127
+ printResult(io, ok('code.gate', { action: 'allow', tool, filePath: extractFilePath(input) }, [], undecidable === null ? [] : [PAYLOAD_DELIVERY_RECIPE]), asJson);
128
+ return;
129
+ }
130
+ printResult(io, fail('code.gate', 'PEAKS_CODE_PROHIBITED_DIRECT_EDIT', verdict.message, {
131
+ action: 'deny',
132
+ tool,
133
+ filePath: verdict.filePath,
134
+ reason: verdict.reason
135
+ }, ['use peaks sub-agent dispatch rd']), asJson);
136
+ }
62
137
  export function registerCodeGateCommand(program, io) {
63
138
  addJsonOption(program
64
139
  .command('code-gate')
@@ -68,48 +143,36 @@ export function registerCodeGateCommand(program, io) {
68
143
  'The gate blocks Edit/Write/MultiEdit on hard-blocked path families ' +
69
144
  '(src/, tests/unit/, tests/integration/, config/, bin/, scripts/) so the ' +
70
145
  'orchestrator is forced to dispatch via `peaks sub-agent dispatch rd`. ' +
71
- 'Allow-listed paths (.peaks/**, skills/**, docs/**) are NOT gated.')
146
+ 'Allow-listed paths (.peaks/**, skills/**, docs/**) are NOT gated. ' +
147
+ 'A payload the gate cannot read is ALLOWED (fail-open) and says so on ' +
148
+ 'stderr with PEAKS_CODE_GATE_UNDECIDABLE — ' +
149
+ 'feed the payload by FILE REDIRECTION, not through a pipe.')
72
150
  .option('--dry-run', 'emit JSON verdict to stdout instead of exit code; useful for tests')
73
151
  .option('--project <path>', 'project the driver lease is resolved against (default: current directory)')).action(async (opts) => {
74
- let raw = '';
75
- try {
76
- raw = await readStdin();
77
- }
78
- catch {
79
- // Empty / unreadable stdin → fail-open allow. The shell-script
80
- // sibling does the same.
81
- raw = '';
82
- }
83
- let parsed = null;
84
- try {
85
- parsed = raw.trim().length > 0 ? JSON.parse(raw) : null;
86
- }
87
- catch {
88
- // Malformed JSON → fail-open allow. Cannot decide safely.
89
- parsed = null;
90
- }
152
+ const parsed = parsePayload(await readPayload());
91
153
  if (parsed === null) {
154
+ reportUndecidable('no stdin payload');
92
155
  if (opts.dryRun === true) {
93
- printResult(io, ok('code.gate', { action: 'allow', reason: 'empty-or-malformed-payload' }, [], ['no stdin payload; allowing']), opts.json);
156
+ printResult(io, ok('code.gate', { action: 'allow', reason: 'empty-or-malformed-payload' }, [], ['no stdin payload; allowing', PAYLOAD_DELIVERY_RECIPE]), opts.json);
94
157
  return;
95
158
  }
96
159
  process.exit(0);
97
160
  }
98
161
  const tool = readToolName(parsed);
99
162
  const input = readToolInput(parsed);
100
- const verdict = decideGateAction(tool, input, resolveDriver(resolveCanonicalProjectRoot(opts.project ?? process.cwd()), parsed));
163
+ const undecidable = undecidableReason(tool, input);
164
+ if (undecidable !== null) {
165
+ reportUndecidable(undecidable);
166
+ }
167
+ // The project root is what the deny families are relative to, so it is
168
+ // resolved ONCE and used twice: to place the caller, and to relate an
169
+ // absolute target path to the project. A path spelled absolutely is the
170
+ // same file as the same path spelled relatively, and both must be judged
171
+ // the same way.
172
+ const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
173
+ const verdict = decideGateAction(tool, input, resolveDriver(projectRoot, parsed), projectRoot);
101
174
  if (opts.dryRun === true) {
102
- if (verdict.action === 'allow') {
103
- printResult(io, ok('code.gate', { action: 'allow', tool, filePath: extractFilePath(input) }, [], []), opts.json);
104
- }
105
- else {
106
- printResult(io, fail('code.gate', 'PEAKS_CODE_PROHIBITED_DIRECT_EDIT', verdict.message, {
107
- action: 'deny',
108
- tool,
109
- filePath: verdict.filePath,
110
- reason: verdict.reason
111
- }, ['use peaks sub-agent dispatch rd']), opts.json);
112
- }
175
+ printDryRunVerdict(io, opts.json === true, { tool, input, verdict, undecidable });
113
176
  return;
114
177
  }
115
178
  if (verdict.action === 'deny') {
@@ -28,6 +28,10 @@ export interface GateInput {
28
28
  export declare const HARD_BLOCKED_PATH_FAMILIES: readonly ["src/", "tests/unit/", "tests/integration/", "config/", "bin/", "scripts/"];
29
29
  /** Allow-listed path prefixes / suffixes — orchestrator may freely Edit/Write these. */
30
30
  export declare const ALLOW_LISTED_PATH_PATTERNS: readonly [".peaks/", ".peaks_", "skills/", "docs/", ".md", "CHANGELOG.md", "README.md"];
31
+ /** The tool names this gate judges. A call under any other name is allowed. */
32
+ export declare const GATED_TOOL_NAMES: readonly ["Edit", "Write", "MultiEdit"];
33
+ /** Is this tool one the gate judges at all? */
34
+ export declare function isGatedTool(tool: GateToolName): boolean;
31
35
  export type GateVerdict = {
32
36
  readonly action: 'allow';
33
37
  } | {
@@ -38,6 +42,30 @@ export type GateVerdict = {
38
42
  };
39
43
  /** Pull the target file path from `input.file_path | input.path | input.notebook_path`. */
40
44
  export declare function extractFilePath(input: Readonly<Record<string, unknown>>): string;
45
+ /**
46
+ * The ONE spelling-independent form of a target path.
47
+ *
48
+ * The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
49
+ * so how the incoming path happens to be SPELLED must not decide the verdict:
50
+ * `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
51
+ * file and must get one verdict. Without this, the same edit is denied in one
52
+ * spelling and allowed in another — and the allow is the one that happens.
53
+ *
54
+ * - separators fold to `/` (a Windows payload spells `src\x.ts`)
55
+ * - a leading `./` is dropped
56
+ * - an ABSOLUTE path inside `projectRoot` becomes project-relative
57
+ * - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
58
+ * THIS project's directories, and a path in another repository is another
59
+ * project's business. That is also what the gate already did with every
60
+ * absolute path, so it is not a widening.
61
+ * - with no `projectRoot` an absolute path cannot be made relative and is
62
+ * left as it is
63
+ *
64
+ * A `..` segment is deliberately NOT resolved: a relative path is relative to
65
+ * the tool call's own working directory, which this module does not know, and
66
+ * resolving it against the project root would be a guess.
67
+ */
68
+ export declare function normalizeGatePath(filePath: string, projectRoot?: string | null): string;
41
69
  /**
42
70
  * Pure decision function. Given the tool name + input object, return
43
71
  * the gate verdict. Tolerates malformed payloads (allow).
@@ -47,5 +75,9 @@ export declare function extractFilePath(input: Readonly<Record<string, unknown>>
47
75
  * `null` are the same verdict as before this parameter existed: the
48
76
  * hard-blocked families deny. Resolution is the caller's job, so this
49
77
  * module keeps no session, lease or filesystem state.
78
+ *
79
+ * `projectRoot` is the root the deny families are relative to. It is what
80
+ * lets an ABSOLUTE path be judged like its relative spelling; without it an
81
+ * absolute path cannot be related to the project and is left alone.
50
82
  */
51
- export declare function decideGateAction(tool: GateToolName, input: Readonly<Record<string, unknown>>, driver?: string | null): GateVerdict;
83
+ export declare function decideGateAction(tool: GateToolName, input: Readonly<Record<string, unknown>>, driver?: string | null, projectRoot?: string | null): GateVerdict;
@@ -18,6 +18,8 @@
18
18
  * logic, usable from any non-Node harness. Both share the same
19
19
  * hard-blocked + allow-listed path families.
20
20
  */
21
+ import { isAbsolute, relative, resolve } from 'node:path';
22
+ import { normalizePath } from '../../shared/path-utils.js';
21
23
  /** Hard-blocked path families — orchestrator MUST NOT Edit/Write these. */
22
24
  export const HARD_BLOCKED_PATH_FAMILIES = [
23
25
  'src/',
@@ -44,6 +46,12 @@ export const ALLOW_LISTED_PATH_PATTERNS = [
44
46
  * this write, because the write it opens is source editing.
45
47
  */
46
48
  const FAST_LANE_DRIVER = 'peaks-race-code';
49
+ /** The tool names this gate judges. A call under any other name is allowed. */
50
+ export const GATED_TOOL_NAMES = ['Edit', 'Write', 'MultiEdit'];
51
+ /** Is this tool one the gate judges at all? */
52
+ export function isGatedTool(tool) {
53
+ return GATED_TOOL_NAMES.includes(tool);
54
+ }
47
55
  /** Pull the target file path from `input.file_path | input.path | input.notebook_path`. */
48
56
  export function extractFilePath(input) {
49
57
  for (const key of ['file_path', 'path', 'notebook_path']) {
@@ -63,6 +71,50 @@ function matchesAny(path, families) {
63
71
  }
64
72
  return null;
65
73
  }
74
+ /** Drop every leading `./` segment: `./src/x.ts` and `src/x.ts` are one path. */
75
+ function stripLeadingDotSegments(path) {
76
+ let out = path;
77
+ while (out.startsWith('./'))
78
+ out = out.slice(2);
79
+ return out;
80
+ }
81
+ /**
82
+ * The ONE spelling-independent form of a target path.
83
+ *
84
+ * The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
85
+ * so how the incoming path happens to be SPELLED must not decide the verdict:
86
+ * `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
87
+ * file and must get one verdict. Without this, the same edit is denied in one
88
+ * spelling and allowed in another — and the allow is the one that happens.
89
+ *
90
+ * - separators fold to `/` (a Windows payload spells `src\x.ts`)
91
+ * - a leading `./` is dropped
92
+ * - an ABSOLUTE path inside `projectRoot` becomes project-relative
93
+ * - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
94
+ * THIS project's directories, and a path in another repository is another
95
+ * project's business. That is also what the gate already did with every
96
+ * absolute path, so it is not a widening.
97
+ * - with no `projectRoot` an absolute path cannot be made relative and is
98
+ * left as it is
99
+ *
100
+ * A `..` segment is deliberately NOT resolved: a relative path is relative to
101
+ * the tool call's own working directory, which this module does not know, and
102
+ * resolving it against the project root would be a guess.
103
+ */
104
+ export function normalizeGatePath(filePath, projectRoot) {
105
+ if (filePath.length === 0)
106
+ return '';
107
+ const slashed = normalizePath(filePath);
108
+ if (!isAbsolute(slashed))
109
+ return stripLeadingDotSegments(slashed);
110
+ if (typeof projectRoot === 'string' && projectRoot.length > 0) {
111
+ const relativePath = normalizePath(relative(resolve(projectRoot), resolve(slashed)));
112
+ if (relativePath.length > 0 && !relativePath.startsWith('..') && !isAbsolute(relativePath)) {
113
+ return stripLeadingDotSegments(relativePath);
114
+ }
115
+ }
116
+ return slashed;
117
+ }
66
118
  /**
67
119
  * Pure decision function. Given the tool name + input object, return
68
120
  * the gate verdict. Tolerates malformed payloads (allow).
@@ -72,19 +124,28 @@ function matchesAny(path, families) {
72
124
  * `null` are the same verdict as before this parameter existed: the
73
125
  * hard-blocked families deny. Resolution is the caller's job, so this
74
126
  * module keeps no session, lease or filesystem state.
127
+ *
128
+ * `projectRoot` is the root the deny families are relative to. It is what
129
+ * lets an ABSOLUTE path be judged like its relative spelling; without it an
130
+ * absolute path cannot be related to the project and is left alone.
75
131
  */
76
- export function decideGateAction(tool, input, driver) {
132
+ export function decideGateAction(tool, input, driver, projectRoot) {
77
133
  // Only gate Edit / Write / MultiEdit.
78
- if (tool !== 'Edit' && tool !== 'Write' && tool !== 'MultiEdit') {
134
+ if (!isGatedTool(tool)) {
79
135
  return { action: 'allow' };
80
136
  }
81
- const filePath = extractFilePath(input);
82
- if (filePath.length === 0) {
137
+ const requestedPath = extractFilePath(input);
138
+ if (requestedPath.length === 0) {
83
139
  // No path → cannot decide; fail-open (allow). The probe side
84
140
  // (`orchestrator-can-do`) handles slice-spec content; this hook
85
141
  // handles file paths only.
86
142
  return { action: 'allow' };
87
143
  }
144
+ // The verdict is about the FILE, not about the spelling of the path that
145
+ // names it, so the path is reduced to the project-relative form the
146
+ // families are written in before anything is matched. The verdict still
147
+ // echoes the path the tool actually asked for.
148
+ const filePath = normalizeGatePath(requestedPath, projectRoot);
88
149
  // Allow-list check first — short-circuits any deny, for every driver.
89
150
  const allowMatch = matchesAny(filePath, ALLOW_LISTED_PATH_PATTERNS);
90
151
  if (allowMatch !== null) {
@@ -100,9 +161,9 @@ export function decideGateAction(tool, input, driver) {
100
161
  return { action: 'allow' };
101
162
  }
102
163
  const reason = `${denyMatch} (orchestrator's hard-blocked path family)`;
103
- const message = `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: ${filePath} matches hard-blocked path family ${reason}; ` +
164
+ const message = `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: ${requestedPath} matches hard-blocked path family ${reason}; ` +
104
165
  `orchestrator MUST NOT Edit/Write these directly. Use: peaks sub-agent dispatch rd --prompt '<your task>' --request-id <rid> --project . --batch-id <uuid>`;
105
- return { action: 'deny', filePath, reason, message };
166
+ return { action: 'deny', filePath: requestedPath, reason, message };
106
167
  }
107
168
  // Anything not in the deny list → allow (e.g. CHANGELOG, README, top-level files).
108
169
  return { action: 'allow' };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.13",
3
+ "version": "4.1.14",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -129,10 +129,10 @@
129
129
  "picomatch": "4.0.7",
130
130
  "yaml": "^2.9.1",
131
131
  "zod": "^4.6.7",
132
- "peaks-loop-internal-runtime": "0.0.53",
133
- "peaks-loop-shared": "0.0.102",
134
- "peaks-loop-shared-channel": "0.0.70",
135
- "peaks-loop-mut": "0.1.67"
132
+ "peaks-loop-mut": "0.1.68",
133
+ "peaks-loop-shared-channel": "0.0.71",
134
+ "peaks-loop-shared": "0.0.103",
135
+ "peaks-loop-internal-runtime": "0.0.54"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",