From f2d797d7d92cc3bd59fcb77aefd93e99e3d4a3a7 Mon Sep 17 00:00:00 2001 From: Munawarx Date: Sat, 25 Jul 2026 22:12:48 +0530 Subject: [PATCH 1/2] docs: state the Linux-only requirement for the exam/replay harness The frozen exam / replay / label-corpus suites use /proc/self/fd + O_NOFOLLOW and error with "race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW" on non-Linux hosts; symlink-rejection paths additionally need symlink-creation rights (e.g. Windows Developer Mode). A contributor on macOS/Windows would see those specific suites red and could mistake it for a regression. - README "Get started": add a Platform note clarifying what runs everywhere (router/matcher/planner/receipts/hooks) vs what requires Linux (bench + replay + label-corpus). - CONTRIBUTING "fast loop": same honest note so contributors don't file false bug reports. Evidence (verified locally on Windows Node v24): score-exam.test.js:447 and label-corpus.test.js:136 throw "race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW"; core router suites (matcher, contract-engine, planner) pass. No source, schema, policy, or dependency changes. Co-Authored-By: Peter --- CONTRIBUTING.md | 2 ++ README.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c40ddec..419b507 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,8 @@ npm run bench # frozen routing/satisfaction benchmark — run it if you touc There is no hidden CI magic yet: the suite you run locally is the gate. If you change routing behavior, paste the before/after bench output in the PR description. +**Platform note (honest).** The router, matcher, planner, receipts, and Claude Code hooks run on any Node ≥18 platform. The frozen **exam / replay / label-corpus** harness (`npm run bench`, `scripts/replay.js`, `scripts/label-corpus.js`, `scripts/score-exam.js`) requires **Linux** — it uses `/proc/self/fd` + `O_NOFOLLOW` for race-safe I/O and errors with `race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW` elsewhere; symlink-rejection paths also need symlink-creation rights (e.g. Windows Developer Mode). If you're on a non-Linux host, expect those specific suites to be red while the core router suites stay green — that's a harness constraint, not a regression you introduced. + ## What goes where * **Quick fixes** (typo, doc bug, obvious regression) → straight to a PR. diff --git a/README.md b/README.md index 7078306..d032d9e 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,8 @@ npx github:Nazim22/leadline init --claude-code # flip to enforce Dry-run mode is the benchmark: it watches your own sessions and shows you your agent’s wrong-source calls, empty receipts, and unproven “done” claims — your data, your numbers — before a single call is ever denied. +**Platform note (stated honestly).** The router, matcher, planner, receipts, and Claude Code hooks run anywhere Node ≥18 runs. The frozen **exam / replay / label-corpus** harness — `npm run bench`, `scripts/replay.js`, `scripts/label-corpus.js`, `scripts/score-exam.js` — requires **Linux** (`/proc/self/fd` + `O_NOFOLLOW` for race-safe I/O); on other platforms those suites error with `race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW`. Symlink-rejection paths in the replay/provenance suites additionally need symlink creation rights (e.g. Windows Developer Mode). This is a harness/platform constraint, not a defect in the router — the enforcement logic it certifies is platform-independent. + ## Policy packs — enforcement with receipts Every shipped rule carries a `why` field with the real measurement behind it. Packs without receipts are opinions. From 2e5b454ca01b3d1645b4cf6e1b1b711557392b67 Mon Sep 17 00:00:00 2001 From: Munawarx Date: Sun, 26 Jul 2026 01:35:14 +0530 Subject: [PATCH 2/2] docs: narrow the Linux-only note to scripts/label-corpus.js (per review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Maintainer review (CHANGES_REQUESTED) corrected an overstatement: I had implied the whole exam/replay/label-corpus harness needs Linux. Verified in the code: - scripts/label-corpus.js:113 hard-throws off Linux (O_NOFOLLOW /proc). - scripts/extract-corpus.js:50 degrades gracefully via (O_NOFOLLOW || 0). - src/benchmark.js:3-7 only needs node:fs/path/perf_hooks + planner + satisfaction — pure and platform-independent, so `npm run bench` runs anywhere Node >=18. Reworded both README and CONTRIBUTING to name label-corpus.js specifically and keep the symlink-rejection note for replay/provenance suites. This matches the project's own rule: a claim ships with the measurement behind it — the note must not overstate the constraint. Co-Authored-By: Peter --- CONTRIBUTING.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 419b507..b02ad9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ npm run bench # frozen routing/satisfaction benchmark — run it if you touc There is no hidden CI magic yet: the suite you run locally is the gate. If you change routing behavior, paste the before/after bench output in the PR description. -**Platform note (honest).** The router, matcher, planner, receipts, and Claude Code hooks run on any Node ≥18 platform. The frozen **exam / replay / label-corpus** harness (`npm run bench`, `scripts/replay.js`, `scripts/label-corpus.js`, `scripts/score-exam.js`) requires **Linux** — it uses `/proc/self/fd` + `O_NOFOLLOW` for race-safe I/O and errors with `race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW` elsewhere; symlink-rejection paths also need symlink-creation rights (e.g. Windows Developer Mode). If you're on a non-Linux host, expect those specific suites to be red while the core router suites stay green — that's a harness constraint, not a regression you introduced. +**Platform note (honest).** The router, matcher, planner, receipts, and Claude Code hooks run on any Node ≥18 platform, and so does `npm run bench`. The corpus labeling harness (`scripts/label-corpus.js`) requires **Linux** — it uses `/proc/self/fd` with `O_NOFOLLOW` for race-safe I/O and fails with `race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW` elsewhere; `extract-corpus.js` degrades gracefully via `(O_NOFOLLOW || 0)`. Some replay and provenance tests also exercise symlink-rejection paths, which need symlink-creation rights (e.g. Windows Developer Mode). If you're on a non-Linux host, expect `scripts/label-corpus.js` to error while the core router suites and `npm run bench` stay green — that's a harness constraint, not a regression you introduced. ## What goes where diff --git a/README.md b/README.md index d032d9e..3455ac6 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ npx github:Nazim22/leadline init --claude-code # flip to enforce Dry-run mode is the benchmark: it watches your own sessions and shows you your agent’s wrong-source calls, empty receipts, and unproven “done” claims — your data, your numbers — before a single call is ever denied. -**Platform note (stated honestly).** The router, matcher, planner, receipts, and Claude Code hooks run anywhere Node ≥18 runs. The frozen **exam / replay / label-corpus** harness — `npm run bench`, `scripts/replay.js`, `scripts/label-corpus.js`, `scripts/score-exam.js` — requires **Linux** (`/proc/self/fd` + `O_NOFOLLOW` for race-safe I/O); on other platforms those suites error with `race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW`. Symlink-rejection paths in the replay/provenance suites additionally need symlink creation rights (e.g. Windows Developer Mode). This is a harness/platform constraint, not a defect in the router — the enforcement logic it certifies is platform-independent. +**Platform note.** The router, matcher, planner, receipts, and Claude Code hooks run anywhere Node ≥18 runs, and so does `npm run bench`. The corpus labeling harness (`scripts/label-corpus.js`) requires **Linux**: it uses `/proc/self/fd` with `O_NOFOLLOW` for race-safe I/O and fails with `race-safe exam I/O requires Linux /proc/self/fd and O_NOFOLLOW` elsewhere. Some replay and provenance tests also exercise symlink-rejection paths, which need symlink creation rights (on Windows, Developer Mode). ## Policy packs — enforcement with receipts