@bookedsolid/rea 0.32.0 → 0.33.0

package/dist/hooks/architecture-review-gate/index.js

@@ -0,0 +1,250 @@
+/**
+ * Node-binary port of `hooks/architecture-review-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #4 — the SIMPLEST tier-1 port.
+ *
+ * PostToolUse Write/Edit advisory. Reads `policy.architecture_review.
+ * patterns` and prints an advisory banner to stderr when the just-
+ * written file path begins with one of the configured prefixes.
+ * ALWAYS exits 0 — this is a nudge, not a gate.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner. (Even though the
+ *      gate is advisory, HALT short-circuits ALL hooks.)
+ *   2. `policy.architecture_advisory: false` short-circuit → exit 0
+ *      silently. The bash hook reads the policy file with a grep
+ *      `architecture_advisory: false`; we mirror via the canonical
+ *      YAML loader.
+ *   3. Read stdin → `tool_input.file_path` (the bash hook uses
+ *      `notebook_path` too via fall-through, but the original
+ *      `jq -r '.tool_input.file_path // empty'` expression does NOT
+ *      fall through to notebook_path. We preserve that exactly).
+ *   4. Empty file_path → exit 0.
+ *   5. Path normalization mirrors `_lib/path-normalize.sh::normalize_path`:
+ *        - Convert backslashes to forward slashes (Windows / Git Bash).
+ *        - URL-decode `%xx` sequences.
+ *        - Strip a leading `<REA_ROOT>/` prefix if present so
+ *          `policy.architecture_review.patterns` can use repo-relative
+ *          patterns.
+ *   6. Read `policy.architecture_review.patterns`. Empty / unset →
+ *      silent no-op (exit 0). The bst-internal profile pins rea-
+ *      source patterns; consumer projects opt in by populating their
+ *      own list.
+ *   7. First prefix match wins. Emit the advisory banner to stderr;
+ *      exit 0.
+ *
+ * Distinct from the other 0.33.0 ports: this gate is POSTToolUse
+ * (fires AFTER the write, advisory only). The shim that invokes it
+ * should NOT fail-closed on missing CLI — the pre-0.33.0 bash hook
+ * was already a silent no-op when the policy was unset.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseWriteHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+/**
+ * Normalize the incoming file path. Mirrors
+ * `hooks/_lib/path-normalize.sh::normalize_path`:
+ *   - backslashes → forward slashes
+ *   - URL-decoded
+ *   - leading `<REA_ROOT>/` stripped (when applicable)
+ *
+ * Pre-0.16.0 the bash hook ONLY stripped the REA_ROOT prefix, which
+ * meant Windows / Git Bash backslash paths bypassed advisory.
+ */
+function normalizePath(rawPath, reaRoot) {
+    let p = rawPath.replace(/\\/g, '/');
+    try {
+        p = decodeURIComponent(p);
+    }
+    catch {
+        // Malformed % escape — leave the string unchanged. The bash
+        // helper's `printf '%b'` behavior is similar (passes through).
+    }
+    // Strip leading <REA_ROOT>/. Compare normalized forms.
+    const normRoot = reaRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (normRoot.length > 0) {
+        if (p === normRoot)
+            return '';
+        const withSep = normRoot + '/';
+        if (p.startsWith(withSep)) {
+            p = p.slice(withSep.length);
+        }
+    }
+    // 2026-05-15 codex round-1 P3 fix: strip chains of leading `./`
+    // segments. Mirrors `_lib/path-normalize.sh::path_canonical_form`.
+    // Pre-fix `./src/gateway/foo.ts` did NOT match the `src/gateway/`
+    // pattern because the leading `./` was preserved. Bash's
+    // path_canonical_form collapses `./` chains, so `./src/...`,
+    // `././src/...`, etc. all reduce to `src/...`.
+    while (p.startsWith('./')) {
+        p = p.slice(2);
+    }
+    return p;
+}
+function buildAdvisoryBanner(filePath, matched) {
+    return [
+        'ARCHITECTURE ADVISORY: Sensitive path modified\n',
+        '\n',
+        `  File: ${filePath}\n`,
+        `  Category: ${matched}\n`,
+        '\n',
+        '  This file is in an architecture-sensitive directory.\n',
+        '  Consider: Does this change maintain backward compatibility?\n',
+        '  Consider: Should this be reviewed by the principal-engineer agent?\n',
+    ].join('');
+}
+/**
+ * Read `policy.architecture_review.patterns`. Returns `[]` on:
+ *   - policy file missing
+ *   - YAML unparseable
+ *   - architecture_review unset
+ *   - architecture_review.patterns unset/empty/non-list
+ *
+ * 2026-05-15 codex round-1 P3 fix: do NOT use `loadPolicy()` here.
+ * The strict zod schema throws on legacy keys / extra fields, which
+ * caused the catch to swallow patterns silently — a legacy policy.yaml
+ * with one unknown key would disable the advisory entirely, with no
+ * indication to the user.
+ *
+ * The bash original used `policy_list` (a non-strict reader). To match
+ * that behavior we read the YAML directly via the same permissive
+ * parser that `rea hook policy-get` uses (`yaml` package's `parse`),
+ * then pull `architecture_review.patterns` as a list of strings. Any
+ * non-string entry is filtered out. Unknown keys ELSEWHERE in the
+ * policy are tolerated — only the patterns subset matters for this
+ * advisory.
+ */
+function loadArchitecturePatterns(reaRoot, onWarning) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        // File missing — bash hook treats this as "advisory disabled".
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        // Unparseable YAML — log to stderr (NOT silent) and return [].
+        // The advisory still short-circuits to exit 0 since this is an
+        // advisory tier, but the user sees a one-line warning instead of
+        // mysterious silence.
+        onWarning('architecture-review-gate: policy.yaml is unparseable; advisory disabled\n');
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const ar = parsed['architecture_review'];
+    if (ar === undefined || ar === null || typeof ar !== 'object' || Array.isArray(ar)) {
+        return [];
+    }
+    const patterns = ar['patterns'];
+    if (!Array.isArray(patterns))
+        return [];
+    const out = [];
+    for (const entry of patterns) {
+        if (typeof entry === 'string' && entry.length > 0) {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Quick policy-disable probe. The bash hook reads
+ * `architecture_advisory: false` (legacy key — pre-0.20.1 toggle)
+ * directly from policy.yaml via grep. The canonical loader doesn't
+ * surface this key (it's not in the strict schema), so we re-read
+ * the raw YAML text. Returns true when the key is present and
+ * literally `false` (no other value disables the hook in the bash
+ * implementation).
+ */
+function isAdvisoryDisabled(reaRoot) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return /^architecture_advisory:\s*false\b/m.test(raw);
+}
+export async function runArchitectureReviewGate(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    // 1. HALT.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr, matched: null };
+    }
+    // 2. Disabled?
+    if (isAdvisoryDisabled(reaRoot)) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    // 3. Stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let filePath = '';
+    try {
+        const payload = parseWriteHookPayload(stdinRaw);
+        filePath = payload.filePath;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            // Advisory tier: silently exit 0 on malformed payload. The bash
+            // hook used `jq -r '.tool_input.file_path // empty'` which
+            // coerces malformed JSON to empty stdout, then exits 0. Mirror
+            // that — never refuse on a parse error in the advisory path.
+            return { exitCode: 0, stderr, matched: null };
+        }
+        throw err;
+    }
+    if (filePath.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    const normalized = normalizePath(filePath, reaRoot);
+    if (normalized.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    const patterns = loadArchitecturePatterns(reaRoot, writeStderr);
+    if (patterns.length === 0) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    let matched = null;
+    for (const pattern of patterns) {
+        if (normalized.startsWith(pattern)) {
+            matched = pattern;
+            break;
+        }
+    }
+    if (matched === null) {
+        return { exitCode: 0, stderr, matched: null };
+    }
+    writeStderr(buildAdvisoryBanner(normalized, matched));
+    return { exitCode: 0, stderr, matched };
+}
+/**
+ * CLI entry — `rea hook architecture-review-gate`.
+ */
+export async function runHookArchitectureReviewGate(options = {}) {
+    const result = await runArchitectureReviewGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}

package/dist/hooks/changeset-security-gate/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Node-binary port of `hooks/changeset-security-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #3.
+ *
+ * Guards `.changeset/*.md` files against two failure modes:
+ *
+ *   1. SECURITY DISCLOSURE LEAK — a GHSA or CVE identifier in a
+ *      changeset file becomes public via CHANGELOG.md when the
+ *      release ships. Block the write.
+ *   2. MISSING OR MALFORMED FRONTMATTER — a changeset without a
+ *      proper frontmatter block is silently ignored by the
+ *      changesets tool, wasting the release entry. Block the write.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Tool filter: only `Write`, `Edit`, `MultiEdit`, `NotebookEdit`.
+ *      Any other tool exits 0.
+ *   3. File-path filter: only `.changeset/*.md` files. The
+ *      `.changeset/README.md` companion is excluded (it's metadata
+ *      for the changesets tool itself).
+ *   4. Security disclosure scan on the resolved content. The
+ *      ordered pattern list is reproduced verbatim. First match wins;
+ *      emit the `MATCHED_PATTERN` placeholder.
+ *   5. MultiEdit short-circuit for frontmatter: MultiEdit's
+ *      `edits[].new_string` is a list of replacement FRAGMENTS, not
+ *      a full file. Running frontmatter validation against the
+ *      concatenated fragments would reject every legitimate edit.
+ *      The bash hook added this exemption in 0.15.0; we mirror it.
+ *      The disclosure scan still runs on the fragments because
+ *      GHSA/CVE patterns match per-fragment without structural
+ *      assumption.
+ *   6. Frontmatter validation:
+ *        a. Must start with `---`.
+ *        b. Must contain at least one `<pkg>: (patch|minor|major)`
+ *           entry inside the first `---`/`---` block. Accepts
+ *           single-quoted, double-quoted, and unquoted package
+ *           names — same explicit alternation form as the bash hook
+ *           (0.15.0 codex round-1 P2-1 fix).
+ *        c. Must have a non-empty description after the closing
+ *           `---`.
+ *
+ * Block emissions use the Claude Code PreToolUse JSON-on-stdout
+ * protocol via `emitJsonBlock`, mirroring `_lib/common.sh::json_output`
+ * — JSON on stdout AND the human reason on stderr, exit 2.
+ */
+import type { Buffer } from 'node:buffer';
+export interface ChangesetSecurityGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+    stdoutWrite?: (s: string) => void;
+}
+export interface ChangesetSecurityGateResult {
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}
+export declare function runChangesetSecurityGate(options?: ChangesetSecurityGateOptions): Promise<ChangesetSecurityGateResult>;
+/**
+ * CLI entry — `rea hook changeset-security-gate`.
+ */
+export declare function runHookChangesetSecurityGate(options?: ChangesetSecurityGateOptions): Promise<void>;
+export declare const __INTERNAL_DISCLOSURE_PATTERNS_FOR_TESTS: readonly string[];
+export declare const __INTERNAL_FRONTMATTER_PATTERN_FOR_TESTS: RegExp;
+export declare const __INTERNAL_BANNERS_FOR_TESTS: {
+    MISSING_FRONTMATTER_BANNER: string;
+    INVALID_FRONTMATTER_BANNER: string;
+    MISSING_DESCRIPTION_BANNER: string;
+};

package/dist/hooks/changeset-security-gate/index.js

@@ -0,0 +1,330 @@
+/**
+ * Node-binary port of `hooks/changeset-security-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #3.
+ *
+ * Guards `.changeset/*.md` files against two failure modes:
+ *
+ *   1. SECURITY DISCLOSURE LEAK — a GHSA or CVE identifier in a
+ *      changeset file becomes public via CHANGELOG.md when the
+ *      release ships. Block the write.
+ *   2. MISSING OR MALFORMED FRONTMATTER — a changeset without a
+ *      proper frontmatter block is silently ignored by the
+ *      changesets tool, wasting the release entry. Block the write.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Tool filter: only `Write`, `Edit`, `MultiEdit`, `NotebookEdit`.
+ *      Any other tool exits 0.
+ *   3. File-path filter: only `.changeset/*.md` files. The
+ *      `.changeset/README.md` companion is excluded (it's metadata
+ *      for the changesets tool itself).
+ *   4. Security disclosure scan on the resolved content. The
+ *      ordered pattern list is reproduced verbatim. First match wins;
+ *      emit the `MATCHED_PATTERN` placeholder.
+ *   5. MultiEdit short-circuit for frontmatter: MultiEdit's
+ *      `edits[].new_string` is a list of replacement FRAGMENTS, not
+ *      a full file. Running frontmatter validation against the
+ *      concatenated fragments would reject every legitimate edit.
+ *      The bash hook added this exemption in 0.15.0; we mirror it.
+ *      The disclosure scan still runs on the fragments because
+ *      GHSA/CVE patterns match per-fragment without structural
+ *      assumption.
+ *   6. Frontmatter validation:
+ *        a. Must start with `---`.
+ *        b. Must contain at least one `<pkg>: (patch|minor|major)`
+ *           entry inside the first `---`/`---` block. Accepts
+ *           single-quoted, double-quoted, and unquoted package
+ *           names — same explicit alternation form as the bash hook
+ *           (0.15.0 codex round-1 P2-1 fix).
+ *        c. Must have a non-empty description after the closing
+ *           `---`.
+ *
+ * Block emissions use the Claude Code PreToolUse JSON-on-stdout
+ * protocol via `emitJsonBlock`, mirroring `_lib/common.sh::json_output`
+ * — JSON on stdout AND the human reason on stderr, exit 2.
+ */
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseWriteHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+/**
+ * Tool names accepted by this gate. Mirrors the bash hook's
+ * `[[ "$TOOL_NAME" != "Write" && ... ]]` chain.
+ */
+const ACCEPTED_TOOLS = new Set([
+    'Write',
+    'Edit',
+    'MultiEdit',
+    'NotebookEdit',
+]);
+/**
+ * Pattern list for the disclosure scan. Order matters — first match
+ * wins, and the matched pattern string lands in the operator banner.
+ */
+const DISCLOSURE_PATTERNS = [
+    /GHSA-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}/,
+    /CVE-[0-9]{4}-[0-9]+/,
+];
+/**
+ * Source strings for the disclosure patterns — these are what the
+ * bash hook emitted in its `MATCHED_PATTERN` placeholder so the
+ * operator banner matches byte-for-byte.
+ */
+const DISCLOSURE_PATTERN_SOURCES = [
+    'GHSA-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}',
+    'CVE-[0-9]{4}-[0-9]+',
+];
+/**
+ * Frontmatter package-bump line. Accepts:
+ *   - "@scope/name": patch
+ *   - '@scope/name': minor
+ *   -  @scope/name : major     (unquoted)
+ * Mirrors the bash hook's explicit-alternation form (codex P2-1).
+ */
+const FRONTMATTER_BUMP_PATTERN = /^("[^"]+"|'[^']+'|[^"'\s]+): (patch|minor|major)/;
+function emitJsonBlock(reason) {
+    const obj = {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    };
+    return { json: JSON.stringify(obj) + '\n', stderr: reason + '\n' };
+}
+/**
+ * Test the file path against the `.changeset/*.md` predicate. Mirrors
+ * the bash hook's two grep calls:
+ *   - must match `\.changeset/[^/]+\.md$`
+ *   - must NOT match `\.changeset/README\.md$`
+ */
+function isChangesetFile(filePath) {
+    if (!/\.changeset\/[^/]+\.md$/.test(filePath))
+        return false;
+    if (/\.changeset\/README\.md$/.test(filePath))
+        return false;
+    return true;
+}
+/**
+ * Find the first matching disclosure pattern. Returns the source
+ * string (for the operator banner) or `null` when none match.
+ */
+function firstDisclosureMatch(content) {
+    for (let i = 0; i < DISCLOSURE_PATTERNS.length; i += 1) {
+        const re = DISCLOSURE_PATTERNS[i];
+        if (re !== undefined && re.test(content)) {
+            return DISCLOSURE_PATTERN_SOURCES[i] ?? null;
+        }
+    }
+    return null;
+}
+/**
+ * Extract the frontmatter block (between the first `---` and the
+ * second `---`). Returns the lines BETWEEN those delimiters, NOT
+ * including the delimiters themselves. Mirrors the bash hook's
+ * `awk '/^---/{count++; if(count==2){exit} next} count==1{print}'`.
+ *
+ * When the second `---` is missing the function returns whatever was
+ * captured after the first `---`; the frontmatter validation regex
+ * then fails for lack of a bump entry, exactly as bash awk would.
+ */
+function extractFrontmatter(content) {
+    const lines = content.split('\n');
+    let dashCount = 0;
+    const out = [];
+    for (const line of lines) {
+        if (/^---/.test(line)) {
+            dashCount += 1;
+            if (dashCount === 2)
+                break;
+            continue;
+        }
+        if (dashCount === 1)
+            out.push(line);
+    }
+    return out.join('\n');
+}
+/**
+ * Extract the first non-empty line AFTER the closing `---`. Mirrors
+ * the bash hook's `awk 'BEGIN{count=0} /^---/{count++; next} count>=2{print}'
+ * | grep -v '^[[:space:]]*$' | head -1`.
+ */
+function extractDescription(content) {
+    const lines = content.split('\n');
+    let dashCount = 0;
+    for (const line of lines) {
+        if (/^---/.test(line)) {
+            dashCount += 1;
+            continue;
+        }
+        if (dashCount < 2)
+            continue;
+        if (line.trim().length === 0)
+            continue;
+        return line;
+    }
+    return '';
+}
+function buildDisclosureBanner(matched) {
+    return `CHANGESET SECURITY GATE: This changeset contains a security advisory identifier (matched: '${matched}').
+
+Do NOT reference GHSA IDs or CVE numbers in changeset files before the advisory is published.
+Changeset files are committed to git — this creates pre-disclosure in public history and CHANGELOG.
+
+CORRECT approach for security fix changesets:
+  Use vague language only — no identifiers, no vulnerability details.
+
+  WRONG:  'fix(hooks): patch GHSA-3w3m-7gg4-f82g — symlink-guard now covers Edit tool'
+  RIGHT:  'security: extend symlink protection to cover all write-capable tools'
+
+  WRONG:  'security: fix CVE-2026-1234 prompt injection via tool descriptions'
+  RIGHT:  'security: harden middleware chain against indirect instruction attacks'
+
+After the release ships:
+  1. Publish the GitHub Security Advisory (Security tab → Advisories → Publish)
+  2. The GHSA becomes the detailed public disclosure document
+  3. Optionally update CHANGELOG.md post-publish to add the GHSA reference`;
+}
+const MISSING_FRONTMATTER_BANNER = `CHANGESET FORMAT GATE: Missing frontmatter block.
+
+Every changeset must start with a frontmatter block specifying which package to bump:
+
+---
+'@bookedsolid/rea': patch
+---
+
+Brief description of what changed and why (close #N if applicable).
+
+Bump types: patch (bug fix/security), minor (new feature), major (breaking change)`;
+const INVALID_FRONTMATTER_BANNER = `CHANGESET FORMAT GATE: Frontmatter does not contain a valid package bump entry.
+
+The frontmatter must include at least one package/bump pair:
+
+---
+'@bookedsolid/rea': patch
+---
+
+Valid bump types: patch | minor | major`;
+const MISSING_DESCRIPTION_BANNER = `CHANGESET FORMAT GATE: Missing description after frontmatter.
+
+Add a meaningful description explaining what changed and why:
+
+---
+'@bookedsolid/rea': patch
+---
+
+fix(gateway): policy-loader now uses async I/O with 500ms TTL cache
+
+Previously, loadPolicy used fs.readFileSync on every tool invocation, blocking
+the event loop under concurrency. Closes #34.`;
+export async function runChangesetSecurityGate(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    let stdout = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    const writeStdout = (s) => {
+        stdout += s;
+        if (options.stdoutWrite)
+            options.stdoutWrite(s);
+    };
+    // 1. HALT.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr, stdout };
+    }
+    // 2. Stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let toolName = '';
+    let filePath = '';
+    let content = '';
+    try {
+        const payload = parseWriteHookPayload(stdinRaw);
+        toolName = payload.toolName;
+        filePath = payload.filePath;
+        content = payload.content;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`changeset-security-gate: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr, stdout };
+        }
+        throw err;
+    }
+    // 3. Tool filter.
+    if (toolName !== '' && !ACCEPTED_TOOLS.has(toolName)) {
+        return { exitCode: 0, stderr, stdout };
+    }
+    // 4. Path filter.
+    if (filePath.length === 0 || !isChangesetFile(filePath)) {
+        return { exitCode: 0, stderr, stdout };
+    }
+    // 5. Disclosure scan (runs for ALL accepted tools incl. MultiEdit).
+    const matched = firstDisclosureMatch(content);
+    if (matched !== null) {
+        const out = emitJsonBlock(buildDisclosureBanner(matched));
+        writeStdout(out.json);
+        writeStderr(out.stderr);
+        return { exitCode: 2, stderr, stdout };
+    }
+    // 6. MultiEdit short-circuit for frontmatter validation. The bash
+    //    hook exits 0 here — the disclosure scan above is the only
+    //    enforcement for fragment-style writes.
+    if (toolName === 'MultiEdit') {
+        return { exitCode: 0, stderr, stdout };
+    }
+    // 7. Frontmatter validation.
+    const firstLine = content.split('\n', 1)[0] ?? '';
+    if (!/^---/.test(firstLine)) {
+        const out = emitJsonBlock(MISSING_FRONTMATTER_BANNER);
+        writeStdout(out.json);
+        writeStderr(out.stderr);
+        return { exitCode: 2, stderr, stdout };
+    }
+    const frontmatter = extractFrontmatter(content);
+    let hasBump = false;
+    for (const line of frontmatter.split('\n')) {
+        if (FRONTMATTER_BUMP_PATTERN.test(line)) {
+            hasBump = true;
+            break;
+        }
+    }
+    if (!hasBump) {
+        const out = emitJsonBlock(INVALID_FRONTMATTER_BANNER);
+        writeStdout(out.json);
+        writeStderr(out.stderr);
+        return { exitCode: 2, stderr, stdout };
+    }
+    const description = extractDescription(content);
+    if (description.length === 0) {
+        const out = emitJsonBlock(MISSING_DESCRIPTION_BANNER);
+        writeStdout(out.json);
+        writeStderr(out.stderr);
+        return { exitCode: 2, stderr, stdout };
+    }
+    return { exitCode: 0, stderr, stdout };
+}
+/**
+ * CLI entry — `rea hook changeset-security-gate`.
+ */
+export async function runHookChangesetSecurityGate(options = {}) {
+    const result = await runChangesetSecurityGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+        stdoutWrite: (s) => process.stdout.write(s),
+    });
+    process.exit(result.exitCode);
+}
+export const __INTERNAL_DISCLOSURE_PATTERNS_FOR_TESTS = DISCLOSURE_PATTERN_SOURCES;
+export const __INTERNAL_FRONTMATTER_PATTERN_FOR_TESTS = FRONTMATTER_BUMP_PATTERN;
+export const __INTERNAL_BANNERS_FOR_TESTS = {
+    MISSING_FRONTMATTER_BANNER,
+    INVALID_FRONTMATTER_BANNER,
+    MISSING_DESCRIPTION_BANNER,
+};