session-orchestrator 3.16.0

package/docs/plugin-architecture-v3.md

@@ -0,0 +1,296 @@
+# Plugin Architecture (v3.0)
+
+Contributor guide for the v3.x codebase. Covers layering, hook anatomy, shared-lib catalog, testing patterns, CI flow, coding conventions, and the `zx`-vs-stdlib heuristic.
+
+Target audience: anyone writing a new hook, adding a shared lib, or extending a skill with Node-side logic. Skill authors writing pure Markdown do not need this guide — see [`CONTRIBUTING.md`](../CONTRIBUTING.md) instead.
+
+## 1. Layering
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Editor runtime (Claude Code / Codex / Cursor IDE)           │
+│   → reads hooks.json, invokes hooks on events               │
+├─────────────────────────────────────────────────────────────┤
+│ hooks/*.mjs                                                 │
+│   PreToolUse, PostToolUse, SessionStart, Stop,              │
+│   SubagentStop — Node processes, stdin JSON in,             │
+│   single-line JSON out (exit 0 = allow, 2 = deny)           │
+├─────────────────────────────────────────────────────────────┤
+│ scripts/lib/*.mjs                                           │
+│   Shared helpers — io, platform, path-utils, config,        │
+│   events, worktree, hardening, common                       │
+├─────────────────────────────────────────────────────────────┤
+│ Node 24+ stdlib  +  zx 8                                    │
+│   fs.promises, path, os, url, crypto, fetch,                │
+│   application logic in ESM; POSIX shell only for run-node   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Skills (`skills/**/*.md`) sit outside this stack — they are instructions for the agent, not code. When a skill needs logic (config parsing, file I/O, subprocess spawning), it invokes a `scripts/lib/*.mjs` module via `node -e` or delegates to a hook.
+
+Codex installation is also layered through public APIs rather than private files. `scripts/codex-install.mjs` validates the tracked manifest and hook contract, calls `codex plugin marketplace add`, calls `codex plugin add`, and verifies the result with `codex plugin list --available --json`. A configured marketplace, an installed+enabled plugin, and trusted/executing hooks are separate postconditions; only the operator can grant the last one in a fresh task through `/hooks`.
+
+The installer repeats `plugin add` on every run so the installed bundle refreshes after local changes. Explicit invalidation comes from the committed `.codex-plugin/plugin.json` version format `<package-version>+codex.<YYYYMMDDHHmmss>`. The contract validator checks the base and UTC timestamp; the installer never mutates the tracked version.
+
+## 2. Hook Anatomy
+
+Every hook follows the same I/O contract, enforced by `scripts/lib/io.mjs`.
+
+### Template
+
+```js
+#!/usr/bin/env node
+// hooks/example.mjs
+import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
+
+async function main() {
+  const input = await readStdin();              // parses JSON stdin with 5s timeout + 1 MB guard
+  const event = JSON.parse(input);
+
+  // Read the event payload. Shape depends on the hook type —
+  // PreToolUse has { tool_name, tool_input }, SessionStart has { session_id, … }, etc.
+  const { tool_name, tool_input } = event;
+
+  if (tool_name === 'Bash' && looksDangerous(tool_input.command)) {
+    emitDeny('Blocked by example policy', { reason: 'dangerous-pattern' });
+    return;
+  }
+
+  emitAllow();
+}
+
+// Top-level try/catch prevents exit code 1 from propagating to the editor.
+main().catch((err) => {
+  emitDeny(`Hook crashed: ${err.message}`, { fatal: true });
+});
+```
+
+### Contract
+
+| Direction | Format |
+|-----------|--------|
+| stdin | Single JSON object from the editor. Type depends on hook event. |
+| stdout | Exactly one line of JSON. `{ "decision": "allow" }`, `{ "decision": "deny", "reason": "…" }`, or `{ "decision": "warn", "message": "…" }`. |
+| exit code | `0` on allow / warn. `2` on deny. **Never exit `1`** — the editor treats that as a hook crash and blocks conservatively. |
+| stderr | Only for debugging. Not surfaced to the user. |
+
+Always wrap `main()` in a top-level `.catch` that calls `emitDeny` — an unhandled exception would otherwise exit 1.
+
+### Registering the hook
+
+Edit `hooks/hooks.json`. Each entry maps an event matcher to the Node command, routed through the `run-node.sh` resolver shim (GH#53 — the harness hook shell does not source `~/.zshrc`, so a bare `node` may be unresolvable even when it works in your terminal):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "sh \"$CLAUDE_PLUGIN_ROOT/hooks/run-node.sh\" \"$CLAUDE_PLUGIN_ROOT/hooks/example.mjs\"" } ] }
+    ]
+  }
+}
+```
+
+Use the harness-native root variable: `$CLAUDE_PLUGIN_ROOT` for Claude Code, `${PLUGIN_ROOT}` inside Codex hook manifests, `$CURSOR_RULES_DIR` for Cursor, and `$PI_PLUGIN_ROOT` for Pi. Never hard-code absolute paths, and never register a bare `node ...` command (the wiring guard in `tests/hooks/run-node-shim.test.mjs` fails on it).
+
+Codex's validated wrapper is intentionally exact:
+
+```json
+{
+  "type": "command",
+  "command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-session-start.mjs\""
+}
+```
+
+`${PLUGIN_ROOT}` is Codex-native. `CODEX_PLUGIN_ROOT` is a compatibility export for shared root resolution, and `SO_PLATFORM=codex` takes precedence in handlers that receive multiple harness signals.
+
+`hooks/hooks-codex.json` is not a copy of the Claude hook file. It contains the six Codex project event slots (`SessionStart`, `PreToolUse`, `PostToolUse`, `SubagentStart`, `SubagentStop`, `Stop`). `SessionEnd`, `PostToolUseFailure`, `PostToolBatch`, and `CwdChanged` are Claude-only and rejected by the Codex contract. Edit-related Claude handlers are also rejected because they do not understand Codex's canonical `apply_patch` payload; keep them absent until a real adapter exists.
+
+Hook registration still does not establish trust. After install or refresh, test in a fresh Codex task and use `/hooks` to inspect and approve the bundle. No installer or validation script may write or bypass that operator decision.
+
+## 3. Shared Lib Catalog
+
+Under `scripts/lib/`. Each module is a focused concern and exports only what callers need.
+
+| Module | 1-liner | Key exports |
+|--------|---------|-------------|
+| **`io.mjs`** | Hook stdin/stdout helpers matching the Claude Code contract | `readStdin`, `emitAllow`, `emitDeny`, `emitWarn`, `emitSystemMessage` |
+| **`platform.mjs`** | OS + editor detection | `SO_OS`, `SO_IS_WINDOWS`, `SO_IS_WSL`, `SO_PATH_SEP`, `SO_STATE_DIR`, `detectPlatform()` |
+| **`path-utils.mjs`** | CWE-23-safe path helpers (null-byte rejection, UNC block, cross-drive escape, locale-stable casing) | `normalizeForMatching`, `isWithin`, `CWE_23_ATTACK_PATTERNS` |
+| **`config.mjs`** | CRLF-tolerant Session Config parser (originally parse-config.sh in v2; byte-exact parity preserved) | `parseSessionConfig`, `readConfigFile`, `getConfigValue` |
+| **`config-schema.mjs`** | Plain-JS validator; validates the 7 mandatory Session Config fields (3 required strings + 4 typed fields) | `validateSessionConfig` (internal `REQUIRED_STRING_FIELDS` constant covers the 3 required strings — not exported) |
+| **`events.mjs`** | Append to `.orchestrator/metrics/events.jsonl` + optional webhook POST | `emitEvent`, `appendEvent` |
+| **`worktree.mjs`** | zx-based git worktree helpers with cross-platform paths | `createWorktree`, `removeWorktree`, `listWorktrees`, `cleanupAllWorktrees` |
+| **`hardening.mjs`** | Scope + command enforcement primitives | `findScopeFile`, `getEnforcementLevel`, `pathMatchesPattern`, `commandMatchesBlocked` |
+| **`common.mjs`** | Grab-bag utilities | `makeTmpPath`, `utcTimestamp`, `readJson`, `writeJson`, `appendJsonl` |
+| **`state-md.mjs`** | Hand-rolled YAML-subset STATE.md parser (never throws) | `parseStateMd`, `serializeStateMd`, `touchUpdatedField` |
+| **`host-identity.mjs`** | Device fingerprint + SSH detection (v3.1 resource-awareness) | `getHostIdentity`, `isSshSession` |
+| **`resource-probe.mjs`** | Live RAM/CPU/process snapshot (v3.1) | `probe`, `evaluate` |
+| **`pre-dispatch-check.mjs`** | Worktree overlap guard before agent dispatch (v3.1) | `checkOverlap` |
+| **`package-manager.mjs`** | Lockfile-based package-manager detection | `detectPackageManager`, `defaultCommands` |
+| **`quality-gates-policy.mjs`** | JSON-Schema policy loader for test/typecheck/lint | `loadQualityGatesPolicy`, `resolveCommand` |
+
+### Import example
+
+```js
+import { readJson, writeJson } from '../scripts/lib/common.mjs';
+import { SO_IS_WINDOWS } from '../scripts/lib/platform.mjs';
+
+const cfg = await readJson('.orchestrator/policy/blocked-commands.json');
+cfg.updated = new Date().toISOString();
+await writeJson('.orchestrator/policy/blocked-commands.json', cfg);
+```
+
+All shared libs are ES modules. Import with explicit `.mjs` extensions — Node's ESM loader does not resolve bare specifiers for relative paths.
+
+## 4. Testing Patterns
+
+Tests live under `tests/` and are run by `npm test` (vitest).
+
+### Directory layout
+
+```
+tests/
+├── lib/               # unit tests for scripts/lib/*.mjs
+├── hooks/             # unit tests for hooks/*.mjs
+├── integration/       # cross-component tests (hook-smoke, parse-config-validator, etc.)
+└── fixtures/          # fixture inputs (CLAUDE.md variants, event payloads, …)
+```
+
+### Stdin mocking for hooks
+
+Hooks read JSON from stdin. The pattern is to spawn the hook as a subprocess and pipe the payload:
+
+```js
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+function runHook(hookPath, payload) {
+  return new Promise((resolveResult) => {
+    const proc = spawn('node', [hookPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += d));
+    proc.stderr.on('data', (d) => (stderr += d));
+    proc.on('close', (code) => resolveResult({ code, stdout, stderr }));
+    proc.stdin.end(JSON.stringify(payload));
+  });
+}
+
+// Usage
+const hookPath = resolve(fileURLToPath(import.meta.url), '../../../hooks/example.mjs');
+const { code, stdout } = await runHook(hookPath, { tool_name: 'Bash', tool_input: { command: 'ls' } });
+expect(code).toBe(0);
+expect(JSON.parse(stdout).decision).toBe('allow');
+```
+
+`tests/integration/hook-smoke.test.mjs` is the canonical reference for this pattern.
+
+### OS-conditional tests
+
+Use `skipIf` / `runIf` with `process.platform`:
+
+```js
+import { describe, it, skipIf } from 'vitest';
+
+describe('symlink escape on posix only', () => {
+  skipIf(process.platform === 'win32')('rejects symlinks outside scope', async () => {
+    // posix-specific test body
+  });
+});
+```
+
+### Spawn helper
+
+For lib tests that invoke real subprocesses (e.g., parity checks against the legacy Bash versions), use the helper in `tests/_spawn-helper.mjs` which handles Windows shell quoting and timeouts.
+
+## 5. CI Flow
+
+`.github/workflows/test.yml` runs the full suite on every push and PR across three OSes.
+
+```
+matrix:
+  os: [ubuntu-latest, macos-latest, windows-latest]
+  node: [20]
+```
+
+`fail-fast: false` so a Windows-only flake does not mask an Ubuntu regression. Each job:
+
+1. Checkouts (SHA-pinned `actions/checkout`).
+2. Installs `jq` via the OS package manager.
+3. `npm ci` — reproducible install from lockfile.
+4. `npm run lint` — ESLint v9 + Prettier.
+5. `npm run typecheck` — `node --check scripts/lib/*.mjs` (syntactic-only; there is no TypeScript yet).
+6. `npm test` — vitest run.
+
+### Debugging Windows-only failures
+
+1. Reproduce locally if possible (Windows VM, GitHub Actions runner image, or a Windows-native dev box).
+2. Check line endings — v3 ships `.gitattributes` with explicit LF rules, but a pre-v3 checkout may have CRLF. Run `git config core.autocrlf false && git rm --cached -r . && git reset --hard`.
+3. Inspect paths — Node on Windows uses `\`, but many libs normalize to `/`. `scripts/lib/path-utils.mjs:normalizeForMatching` is the canonical normalizer.
+4. Check tmpdir — `os.tmpdir()` on Windows returns `C:\Users\…\Temp`, which trips tests that hard-coded `/tmp`.
+5. Read the CI logs: `gh run view --log <run-id>` or download the artifact from the Actions tab.
+
+## 6. Coding Conventions
+
+Enforced by ESLint v9 + Prettier. See `eslint.config.js` and `.prettierrc`.
+
+- **ES modules only.** Every new Node file uses `.mjs`, `import`/`export`, top-level `await`. No CommonJS (`require`, `module.exports`).
+- **Single quotes, 100-column width, LF line endings.** Prettier handles this automatically — `npm run lint:fix` fixes offenders in place.
+- **`_`-prefix for intentionally-unused variables.** `no-unused-vars` allows `_`-prefixed names (including destructure patterns). Example: `const [_status, stdout] = await run(cmd);`.
+- **Path handling.** Never concatenate path strings with `+` or `\``. Always `path.join(...)`. For path comparisons, go through `path-utils.mjs:normalizeForMatching`.
+- **Subprocess spawning.** Prefer `zx`'s `$` tag for shell-like commands (handles quoting). For untrusted input, pass arguments via `child_process.spawn` arg arrays, not concatenated shell strings.
+- **Error handling.** Hooks: top-level `.catch` → `emitDeny`. Libs: throw with context (`throw new Error('parseConfig: missing field X')`) and let the caller decide. Never swallow errors silently except on best-effort cleanup paths, and warn to stderr when you do.
+- **No `console.log` in libs or hooks.** `stdout` is reserved for the hook I/O contract. Diagnostics go to `stderr` or `events.jsonl` via `events.mjs`.
+- **`===` / `!==` always.** `==`/`!=` is banned (`eqeqeq`).
+- **No `var`.** `const` by default, `let` when reassignment is genuinely needed.
+- **Tests are `.test.mjs` or `.spec.mjs`.** vitest picks them up automatically under `tests/`.
+
+## 7. When to use zx vs. Node stdlib
+
+Rule of thumb:
+
+| Use zx (`$`, `nothrow`) | Use Node stdlib |
+|------------------------|-----------------|
+| Spawning external commands (`git`, `glab`, `gh`, `npm`) | Reading/writing files |
+| Shell-like composition (pipes, redirection) | Parsing JSON |
+| Cross-platform quoting (zx handles spaces, quotes) | HTTP requests (`fetch`) |
+| Commands that may fail and whose failure you want to inspect (`nothrow`) | Timers, signals, crypto |
+
+Example — **good zx usage**:
+
+```js
+import { $, nothrow } from 'zx';
+
+const { stdout: branch } = await $`git rev-parse --abbrev-ref HEAD`;
+const { exitCode } = await nothrow($`git worktree remove ${tmpDir}`);
+if (exitCode !== 0) {
+  // best-effort cleanup; don't crash
+}
+```
+
+Example — **use stdlib instead**:
+
+```js
+// BAD — zx for a pure file read
+const { stdout } = await $`cat ${path}`;
+
+// GOOD — use fs
+import { readFile } from 'node:fs/promises';
+const content = await readFile(path, 'utf-8');
+```
+
+Reasons to prefer stdlib when possible:
+
+- **Speed.** Spawning a shell to `cat` a file is ~100× slower than `fs.readFile`.
+- **Windows portability.** `cat` is absent on stock Windows; `readFile` is universal.
+- **Error messages.** `ENOENT` from stdlib is more precise than a shell exit code.
+
+Reasons zx wins when it does:
+
+- **Git + CLI tooling.** `git`, `glab`, `gh` have rich output formats and exit-code semantics that zx preserves.
+- **Quote handling.** zx's `$` template literal handles argument quoting on Windows and POSIX consistently. `child_process.exec` with concatenated strings does not.
+
+---
+
+Questions or gaps? Open an issue at [session-orchestrator](https://github.com/Kanevry/session-orchestrator/issues) with label `area:docs`.

package/docs/pm-skills-marketplace.md

@@ -0,0 +1,114 @@
+# `phuryn/pm-skills` — Install-Alongside Guidance
+
+> Companion doc for the 2026-07-05 `phuryn/pm-skills` evaluation (Epic #750,
+> issue #761). Verdict: **crib the proven techniques, don't vendor the
+> marketplace.** The cribbed techniques already live natively in `/grill`,
+> `/brainstorm`, `/plan`, and the `/discovery` `feature` scope (see § Overlap
+> table below). This doc is for the narrower case where a *product* repo
+> wants the full `phuryn/pm-skills` roster installed side-by-side.
+
+## When to install alongside
+
+`phuryn/pm-skills` (68-skill PM marketplace, MIT license, Claude-Code-shaped)
+is worth installing **in addition to** this plugin when a repo has a genuine,
+recurring PM-workflow need that produces standalone artifacts this plugin
+does not generate:
+
+- **Product-heavy repos** — Ventures-produkt-repos, client MVPs with an
+  active PM/product-owner role — that run discovery interviews, maintain a
+  roadmap document, or keep persona/Opportunity-Solution-Tree artifacts as
+  living deliverables (not one-off planning inputs).
+- The team wants those artifacts as their own documents (roadmap.md,
+  personas.md, OST diagrams) rather than folded into a PRD or an interrogation
+  transcript.
+- Cursor-IDE parity is not a requirement for that repo — `phuryn/pm-skills`
+  targets Claude-Code-shaped skills with no guarantee of cross-platform
+  support.
+
+## When NOT to install alongside
+
+- **Infrastructure / tooling repos** (this repo is the reference case). The
+  evidence-based slice of PM discipline — assumption interrogation,
+  divergent ideation, opportunity ranking, and evidence-anchored
+  feature-intent findings — is already native here:
+  - `/grill` — kill-assumption operationalization (Fails-if / Evidence-this-week
+    / Kill-criterion / Cheapest-test) + pre-mortem Tiger/Paper-Tiger/Elephant
+    taxonomy, part of the Six Tactics in `skills/grill/soul.md`.
+  - `/brainstorm` — three-lens (PM / Designer / Engineer) divergent ideation
+    pass plus Mom-Test interview discipline, in `skills/brainstorm/SKILL.md`.
+  - `/plan` — Opportunity Score ranking, Impact×Risk 2×2 triage, and an
+    optional job-story format, in `skills/plan/SKILL.md` / `mode-feature.md`.
+  - `/discovery feature` — grounded, grep-verified intent-drift and
+    stubbed/dead-feature probes (`skills/discovery/probes-feature.md`),
+    routing judgment-based PM work (OST, personas, market-sizing) out to
+    `/brainstorm`/`/plan` rather than treating it as a verified finding.
+- A second, un-integrated 68-skill roster would not participate in this
+  plugin's session-config, quality gates, or `/discovery` verification
+  pipeline (PSA-006) — see § Warnings below.
+
+## How to install
+
+`phuryn/pm-skills` follows the same Claude Code plugin-marketplace mechanism
+this plugin itself ships through (see `README.md` § Install):
+
+```text
+/plugin marketplace add phuryn/pm-skills
+/plugin install <skill-name>@phuryn
+```
+
+Consult the `phuryn/pm-skills` repository (github.com/phuryn/pm-skills) for
+the exact marketplace slug and the current skill roster — this doc does not
+duplicate that upstream README. Install only the specific skills a repo
+needs (roadmap, persona, OST artifact generation) rather than the full
+roster, to limit auto-dispatch noise (see § Warnings).
+
+## Overlap / Abgrenzung
+
+| Capability | Overlap with this plugin | Where it lives | Verdict |
+|---|---|---|---|
+| Assumption interrogation / red-teaming a plan | `strategy-red-team`-class pm-skills ↔ `/grill` | `skills/grill/soul.md` (Six Tactics, kill-assumption workup, pre-mortem) | Overlap — prefer `/grill` (session/gate-integrated, codebase-grounded) |
+| Divergent ideation / brainstorming | `brainstorm-ideas-*`-class pm-skills ↔ `/brainstorm` | `skills/brainstorm/SKILL.md` (three-lens PM/Designer/Engineer pass, Mom-Test) | Overlap — prefer `/brainstorm` (HARD-GATE + PRD hand-off already wired) |
+| PRD generation / feature scoping / prioritization | `create-prd`-class pm-skills ↔ `/plan feature` | `skills/plan/SKILL.md`, `mode-feature.md` (Opportunity Score, 2×2 risk triage, job-story option) | Overlap — prefer `/plan` (researched Q&A engine, issue creation, appetite/scope discipline already wired) |
+| Documented-vs-enforced intent auditing | No pm-skills equivalent | `/discovery feature` (`skills/discovery/probes-feature.md`) | Unique to this plugin — grep-verified, not judgment-based |
+| Roadmap documents, stakeholder maps, persona trees as standalone artifacts | No equivalent here — this plugin folds personas/roadmap input into PRDs, not standalone living documents | `phuryn/pm-skills` | Unique to pm-skills — install alongside if a repo needs these as first-class artifacts |
+| Opportunity Solution Tree (OST) as a maintained document | No equivalent here (OST reasoning is routed out of `/discovery`'s verified pipeline per its Non-Goals) | `phuryn/pm-skills` | Unique to pm-skills |
+| Market-sizing / competitive-landscape docs | No equivalent here | `phuryn/pm-skills` | Unique to pm-skills |
+
+Rule of thumb: where a technique overlaps, this plugin's version wins because
+it is wired into session lifecycle, quality gates, and issue creation.
+Where the artifact is a standalone PM document this plugin was never
+designed to produce, `phuryn/pm-skills` fills a real gap — install it
+alongside for those repos only.
+
+## Warnings
+
+- **Roster size → auto-dispatch noise.** Installing the full 68-skill roster
+  alongside this plugin's own skill catalog increases the surface
+  `auto-skill-dispatch` phrase-matching has to disambiguate against. Prefer
+  installing only the specific skills a repo actually uses.
+- **Claude Code only.** `phuryn/pm-skills` is Claude-Code-shaped with no
+  Cursor IDE (or Codex CLI / Pi) parity guarantee. This plugin maintains
+  cross-platform support (see `README.md` § Install) — a repo that also runs
+  Cursor sessions loses parity the moment it depends on a pm-skills-only
+  workflow.
+- **No session-config or gate integration.** pm-skills artifacts do not
+  participate in this plugin's Session Config, quality gates, or
+  `/discovery` PSA-006 verification discipline. Treat its output as an
+  independent artifact stream, not something `/close` or the wave-executor
+  will track.
+- **Sunset risk.** An installed-but-rarely-used skill from the roster is a
+  `sunset-review` candidate within a session or two — install narrowly, or
+  expect churn.
+
+## See Also
+
+- `README.md` § Install — the plugin-marketplace install mechanism this doc
+  reuses.
+- `skills/grill/soul.md`, `skills/brainstorm/SKILL.md`, `skills/plan/SKILL.md`
+  — the native crib targets (Six Tactics, three-lens ideation, Opportunity
+  Score/2×2/job-story).
+- `skills/discovery/probes-feature.md` — the grep-verified intent-drift and
+  stubbed-dead-feature probes that keep evidence-based PM findings inside
+  the verified pipeline.
+- Epic #750 / issue #761 — the evaluation and companion-doc tracking issue
+  this document closes.

package/docs/policy-cache-validation-2026-04-28.md

@@ -0,0 +1,118 @@
+# Policy-Cache Effectiveness Validation (#266)
+
+**Date:** 2026-04-28  
+**Issue:** #266 — [Follow-up #250] Validate policy-cache effectiveness under Claude Code subprocess-per-call hook model  
+**Measurement script:** `scripts/measure-policy-cache-effectiveness.mjs`  
+**Environment:** Darwin 25.3.0, Node.js v24.13.1
+
+---
+
+## Background
+
+Issue #250 introduced `scripts/lib/quality-gates-cache.mjs` — a JSONL file-based cache that persists quality-gate Baseline results to `.orchestrator/metrics/baseline-results.jsonl`. The concern raised in #266 was that under Claude Code's subprocess-per-call hook model (each hook invocation spawns a fresh Node.js process), any *in-process* memoisation would be useless because process memory is discarded after every hook run.
+
+Two cache layers were audited:
+
+| Module | Mechanism | Claim |
+|---|---|---|
+| `quality-gates-cache.mjs` | Append-only JSONL on disk | Baseline results persist across waves |
+| `quality-gates-policy.mjs` | Synchronous `fs.readFileSync` | No caching claim — reads the policy file fresh every call |
+
+---
+
+## Findings
+
+### 1. Baseline-Result Cache (`quality-gates-cache.mjs`)
+
+**Cache mechanism:** JSONL file — reads and writes `.orchestrator/metrics/baseline-results.jsonl` on every call. There is **no in-process memoisation**. The file is the cache.
+
+**Subprocess-per-call model (8 subprocesses):**
+
+| Metric | Value |
+|---|---|
+| Hit rate | 100% (8/8) |
+| Mean call time (self-reported) | 0.456 ms |
+| Median call time | 0.453 ms |
+| Persists across subprocess boundaries | **Yes** |
+
+**Multi-call-in-process model (5 calls, same process):**
+
+| Call | Time |
+|---|---|
+| Cold (#1) | 0.220 ms |
+| Warm mean (#2–5) | 0.065 ms |
+| Hit rate | 100% |
+
+**Conclusion:** The cache is fully effective under the subprocess-per-call model. Because persistence is file-based (JSONL), each new subprocess reads the same on-disk record and gets a cache hit as long as the validity criteria are met (`session_start_ref` match, `dependency_hash` match, TTL, all-pass results). The 3.4× speedup from cold→warm in a single process (0.220 ms → 0.065 ms) is from OS page-cache, not module-level memoisation.
+
+**The issue concern is a non-issue:** The cache was never designed around in-process memory. It deliberately uses disk I/O for cross-process durability.
+
+### 2. Policy File Loader (`quality-gates-policy.mjs`)
+
+**Cache mechanism:** None. Every call reads `.orchestrator/policy/quality-gates.json` synchronously via `fs.readFileSync`. No in-process memoisation, no file-based cache.
+
+**Subprocess-per-call model (8 subprocesses, no policy file present):**
+
+| Metric | Value |
+|---|---|
+| Policy found | 0/8 (no `quality-gates.json` in test repo) |
+| Mean call time | 0.098 ms |
+| Median call time | 0.096 ms |
+
+**Multi-call-in-process model (5 calls):**
+
+| Call | Time |
+|---|---|
+| Cold (#1) | 0.044 ms |
+| Warm mean (#2–5) | 0.003 ms |
+
+**Conclusion:** The 14.7× in-process speedup (0.044 ms → 0.003 ms) is entirely from OS page-cache. This module makes **no caching claims** — it is a policy *loader*, not a policy *cache*. At sub-0.1 ms per call even in the subprocess model, adding memoisation would provide no measurable benefit to hook latency.
+
+---
+
+## Subprocess-Per-Call Hook Model Analysis
+
+Claude Code spawns a fresh Node.js process for each hook event. The process startup overhead (Node.js bootstrap, ESM import chain) is **not measured here** — the timings above are for the module logic only, excluding the ~50–100 ms Node.js startup cost that dominates hook wall-clock time.
+
+**Critical finding:** The `quality-gates-cache.mjs` module is called from `skills/wave-executor/wave-loop.md` inside the coordinator session (a long-running Claude Code process), **not** from hook handlers. This means the subprocess-per-call concern does not apply to the primary usage of this cache. The cache is invoked as an LLM-directed inline script call within the coordinator's context, not as a Claude Code hook.
+
+Hook handlers (`hooks/*.mjs`) do not import `quality-gates-cache.mjs` at all. They handle scope enforcement, destructive-command guarding, and session events — none of which use the baseline-result cache.
+
+---
+
+## Raw Numbers (2026-04-28T06:42:22Z)
+
+```json
+{
+  "config": { "subprocessCount": 8, "inprocessCount": 5 },
+  "cache_subprocess_hitRate": 1.0,
+  "cache_subprocess_medianMs": 0.453,
+  "cache_subprocess_meanMs": 0.455,
+  "cache_inprocess_coldMs": 0.220,
+  "cache_inprocess_warmMeanMs": 0.065,
+  "policy_subprocess_medianMs": 0.096,
+  "policy_inprocess_coldMs": 0.044,
+  "policy_inprocess_warmMeanMs": 0.003
+}
+```
+
+---
+
+## Recommendation: KEEP (no changes needed)
+
+1. **`quality-gates-cache.mjs` — KEEP as-is.** The file-based JSONL design is the correct choice for a subprocess-hostile environment. It achieves 100% hit-rate across fresh subprocesses when the validity criteria are met. Sub-millisecond call latency is negligible relative to the quality-gate commands it short-circuits (typecheck + test = typically 10–60 seconds).
+
+2. **`quality-gates-policy.mjs` — KEEP as-is.** Not a cache, does not claim to be one. The 0.096 ms per-call cost in the subprocess model is acceptable. Adding in-process memoisation would only benefit callers that invoke it multiple times in a single process, and the current warm-path latency (0.003 ms from OS page-cache) is already negligible.
+
+3. **No action on issue #266's concern** that "the cache may not survive between calls." It does survive, by design. The misconception is that the cache is in-process memory — it is not. The JSONL file persists until TTL expiry (7 days), session-ref changes, or dependency hash changes.
+
+4. **Optional future improvement (low priority):** An mtime-based shortcut in `loadLatestBaselineResult` could skip the full JSONL parse on repeated reads within a session if the file mtime hasn't changed. Current latency (~0.5 ms/call) does not justify this complexity.
+
+---
+
+## Files
+
+- `scripts/measure-policy-cache-effectiveness.mjs` — instrumentation script (supports `--json`, `--subprocess-count`, `--inprocess-count`, `--repo-root`)
+- `docs/policy-cache-validation-2026-04-28.md` — this document
+- `tests/scripts/measure-policy-cache-effectiveness.test.mjs` — smoke test (script runs, emits valid JSON)
+- `skills/quality-gates/SKILL.md` — `§ Baseline Cache (#258)` — citation updated with validation reference