session-orchestrator 3.16.0

package/scripts/lib/resource-probe.mjs

@@ -0,0 +1,95 @@
+/**
+ * resource-probe.mjs — live RAM/CPU/process snapshot for adaptive session planning.
+ *
+ * Probes current host load at session-start (and optionally inside wave planning)
+ * so `agents-per-wave` and Docker-usage decisions can adapt to real resource
+ * pressure rather than static config defaults.
+ *
+ * Part of v3.1.0 Epic #157, Sub-Epic #158 (A+B). Issue #163.
+ * Extended in v3.2 Phase C-2 (#296): swap_used_mb + memory_pressure_pct_free signals.
+ *
+ * Snapshot shape:
+ *   {
+ *     timestamp: '2026-04-19T11:00:00Z',
+ *     ram_free_gb: 3.2,
+ *     ram_used_pct: 78,
+ *     cpu_load_1m: 2.4,
+ *     cpu_load_pct: 65,
+ *     claude_processes_count: 3 | null,
+ *     codex_processes_count: 0 | null,
+ *     other_node_processes: 12 | null,
+ *     zombie_processes_count: 1 | null,
+ *     swap_used_mb: 512 | null,
+ *     memory_pressure_pct_free: 42 | null,
+ *     ram_available_gb: 82.5 | null,   // macOS: free + reclaimable (vm_stat); null elsewhere (#667)
+ *     probe_duration_ms: 45,
+ *   }
+ *
+ * process-count fields fall back to `null` when the process-list command fails
+ * (e.g. sandboxed environments). Consumers treat `null` as "unknown".
+ *
+ * swap_used_mb: null on Windows/unknown or on spawn/parse failure.
+ * memory_pressure_pct_free: null on Linux/Windows/unknown or on failure.
+ *
+ * Implementation split in #287 (hotspot 2/2):
+ *   - scripts/lib/resource-probe/parsers.mjs      — pure output parsers
+ *   - scripts/lib/resource-probe/probe-platform.mjs — platform sampling I/O
+ *   - scripts/lib/resource-probe/evaluate.mjs     — verdict + threshold logic
+ */
+
+import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctFree, ramAvailableGb } from './resource-probe/probe-platform.mjs';
+
+// ---------------------------------------------------------------------------
+// Re-exports — preserve public API for all existing callers
+// ---------------------------------------------------------------------------
+
+export { evaluate } from './resource-probe/evaluate.mjs';
+export { parseEtimeToMinutes, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
+
+// ---------------------------------------------------------------------------
+// Public API — probe()
+// ---------------------------------------------------------------------------
+
+/**
+ * Capture a live resource snapshot of the current host.
+ * @param {object} [opts]
+ * @param {boolean} [opts.skipProcessCounts] — skip process listing (faster in tests)
+ * @param {boolean} [opts.skipExtendedSignals] — skip swap + memory_pressure calls (faster in tests)
+ * @param {number|null} [opts.zombieThresholdMin] — when non-null, detect zombie Claude/Node
+ *   processes older than this many minutes with low CPU. Default null (feature disabled).
+ * @returns {Promise<object>}
+ */
+export async function probe(opts = {}) {
+  const start = Date.now();
+  const ram = ramSnapshot();
+  const cpu = cpuSnapshot();
+  const zombieThresholdMin = opts.zombieThresholdMin ?? null;
+  const procs = opts.skipProcessCounts
+    ? { claude_processes_count: null, codex_processes_count: null, other_node_processes: null, zombie_processes_count: null }
+    : await processCounts(zombieThresholdMin);
+
+  let swap_used_mb = null;
+  let memory_pressure_pct_free = null;
+  let ram_available_gb = null;
+  if (!opts.skipExtendedSignals) {
+    [swap_used_mb, memory_pressure_pct_free, ram_available_gb] = await Promise.all([
+      swapUsedMb(),
+      memoryPressurePctFree(),
+      ramAvailableGb(),
+    ]);
+  }
+
+  const duration = Date.now() - start;
+  return {
+    timestamp: new Date().toISOString(),
+    ...ram,
+    ...cpu,
+    ...procs,
+    swap_used_mb,
+    memory_pressure_pct_free,
+    // macOS-only numeric available-RAM (free + reclaimable) from vm_stat; null
+    // on Linux/Windows/unknown where os.freemem() is already accurate (#667).
+    ram_available_gb,
+    probe_duration_ms: duration,
+  };
+}

package/scripts/lib/rule-loader.mjs

@@ -0,0 +1,552 @@
+/**
+ * Rule Loader — issue #336 glob-scoped rules + #694 rule-activation foundation
+ * + #795 `paths:` alias.
+ *
+ * Reads `.claude/rules/*.md` files, parses optional YAML frontmatter, and
+ * returns the subset of rules applicable to a given set of file paths and
+ * activation axes.
+ *
+ * Rules with no `globs:`/`paths:` frontmatter are always-on (loaded for every
+ * wave). Rules with `globs:` (or the `paths:` alias — issue #795) load only
+ * when at least one `scopePath` matches at least one glob pattern.
+ *
+ * `paths:` is a same-shape alias for `globs:` (issue #795) — some repos use a
+ * `paths:` frontmatter convention instead of `globs:` (e.g. projects-baseline:
+ * 26 rule files, all `paths:`, 0 `globs:`). Before #795 these repos'
+ * path-scoped rules were silently misclassified as always-on, inflating the
+ * `instruction-budget-guard.mjs` (#687) always-on count with a false positive.
+ * `paths:` supports the identical inline-array and block-list forms as
+ * `globs:`. Precedence when BOTH keys are present on the same rule: `globs:`
+ * wins (silently — no merge, no warning) and `paths:` is ignored entirely.
+ *
+ * A rule file MAY carry a leading single-line provenance header before its
+ * frontmatter block — the vendoring pipeline (`scripts/rules-sync.mjs`)
+ * requires a first-line `<!-- source: session-orchestrator plugin
+ * (canonical: ...) -->` comment on every vendored rule. The frontmatter
+ * parser tolerates any leading run of blank lines and/or single-line HTML
+ * comments before the opening `---`, so a vendored rule keeps its `globs:`
+ * scoping and scalar meta instead of silently falling back to always-on.
+ * Only single-line comments are tolerated (no multi-line comment blocks);
+ * files with no header, or starting directly with `---`, parse exactly as
+ * before.
+ *
+ * Beyond the `globs:` key (issue #336), the frontmatter parser also captures
+ * these scalar activation keys (issue #694), surfaced on each RuleEntry:
+ *   - `description`   (string)
+ *   - `mode`          (string)   — see mode-gating below
+ *   - `host-class`    (string)   — see host-class-gating below; surfaced as `hostClass`
+ *   - `alwaysApply`   (boolean)  — DISTINCT from the `alwaysOn` "no globs" flag
+ *   - `expires-at`    (string)   — ISO date; see expiry gating below; surfaced as `expiresAt`
+ *   - `learning-key`  (string)   — surfaced as `learningKey`
+ *   - `auto-generated`(boolean)  — surfaced as `autoGenerated`
+ *   - `confidence`    (number)
+ * Unknown keys are still ignored without error, and malformed frontmatter still
+ * falls back to always-on (a rule is never silently dropped).
+ *
+ * Deterministic gating (issue #694) runs after a successful frontmatter parse
+ * and applies to BOTH always-on and glob-matched candidate rules — a rule must
+ * pass ALL active gates to be included:
+ *   - Expiry: a rule with a parseable `expires-at` strictly before `now` is
+ *     EXCLUDED (with a mandatory stderr WARN). A malformed `expires-at` never
+ *     excludes (fail-open).
+ *   - Mode-gating: when the `mode` param is non-null and the rule declares a
+ *     `mode` that differs, the rule is EXCLUDED. A null `mode` param disables
+ *     mode filtering; a rule without a `mode` key always passes.
+ *   - Host-class-gating: identical logic against the `hostClass` param vs the
+ *     rule's `host-class` value.
+ *
+ * Parse errors fall back to always-on — a rule is never silently dropped.
+ *
+ * @module rule-loader
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { createRequire } from 'node:module';
+
+// ---------------------------------------------------------------------------
+// Picomatch integration (available in the project's node_modules).
+// We resolve it dynamically so the module stays loadable in environments where
+// picomatch is absent — the inline fallback glob-to-RegExp takes over then.
+// ---------------------------------------------------------------------------
+
+let _picomatch = null;
+
+function getPicomatch() {
+  if (_picomatch !== null) return _picomatch;
+  try {
+    const require = createRequire(import.meta.url);
+    _picomatch = require('picomatch');
+  } catch {
+    // picomatch not available — will use inline fallback
+    _picomatch = false;
+  }
+  return _picomatch;
+}
+
+/**
+ * Minimal glob-to-RegExp fallback used only when picomatch is absent.
+ * Handles `**`, `*`, and literal character matching.
+ *
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+function globToRegExp(pattern) {
+  // Normalize Windows separators
+  const p = pattern.replace(/\\/g, '/');
+  let re = '';
+  let i = 0;
+  while (i < p.length) {
+    const c = p[i];
+    if (c === '*' && p[i + 1] === '*') {
+      // `**` — match zero or more path segments
+      re += '.*';
+      i += 2;
+      // Consume optional trailing separator
+      if (p[i] === '/') i++;
+    } else if (c === '*') {
+      // `*` — match any characters except separator
+      re += '[^/]*';
+      i++;
+    } else if (c === '?') {
+      re += '[^/]';
+      i++;
+    } else if (c === '.') {
+      re += '\\.';
+      i++;
+    } else {
+      // Escape regex-special characters
+      re += c.replace(/[$()+[\]^{|}]/g, '\\$&');
+      i++;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Returns true when `filePath` matches `globPattern` using picomatch (or the
+ * inline fallback when picomatch is absent).
+ *
+ * @param {string} filePath - path relative to repo root, forward-slash separated
+ * @param {string} globPattern
+ * @returns {boolean}
+ */
+function matchGlob(filePath, globPattern) {
+  const pm = getPicomatch();
+  if (pm) {
+    return pm.isMatch(filePath, globPattern, { dot: true });
+  }
+  return globToRegExp(globPattern).test(filePath);
+}
+
+// ---------------------------------------------------------------------------
+// Minimal YAML frontmatter parser (matches state-md.mjs style)
+// ---------------------------------------------------------------------------
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+// A single header line is either blank or a complete single-line HTML
+// comment (`<!-- ... -->` on one line). Multi-line comment blocks are
+// deliberately NOT supported — the vendoring convention is a single first
+// line, and tolerating a few stacked comment lines (each matching this RE)
+// is sufficient.
+const HEADER_LINE_RE = /^[ \t]*(?:<!--.*-->)?[ \t]*$/;
+
+/**
+ * Skips a leading run of blank lines and/or single-line HTML comments
+ * (`<!-- ... -->`) at the very start of a rule file's contents, so the
+ * frontmatter opener (`---`) can be found even when the vendoring pipeline's
+ * mandatory provenance header precedes it. Stops at the first line that is
+ * neither blank nor a complete single-line comment.
+ *
+ * @param {string} contents - raw file contents
+ * @returns {string} contents starting at the first non-header line (empty
+ *   string when the entire content is header lines)
+ */
+function stripLeadingProvenanceHeader(contents) {
+  const lines = contents.split(/\r?\n/);
+  let idx = 0;
+  while (idx < lines.length && HEADER_LINE_RE.test(lines[idx])) {
+    idx++;
+  }
+  return lines.slice(idx).join('\n');
+}
+
+// Scalar activation keys captured (issue #694 + #692). The `globs` key keeps
+// its dedicated sequence/flow handling and is NOT routed through this table.
+const SCALAR_META_KEYS = new Set([
+  'description',
+  'mode',
+  'host-class',
+  'alwaysApply',
+  'expires-at',
+  'learning-key',
+  'auto-generated',
+  'confidence',
+  'tier',
+]);
+
+/**
+ * Parses the YAML frontmatter block for the `globs:` field (issue #336),
+ * its `paths:` alias (issue #795), and the scalar activation keys (issue #694).
+ *
+ * Returns:
+ *   - `{ globs: string[] | null, meta: object }` on success
+ *   - throws `Error` on malformed frontmatter so the caller can fall back
+ *
+ * `globs` is `null` when no frontmatter, and neither `globs:` nor `paths:` is
+ * present (always-on). `paths:` is parsed with the identical inline-array and
+ * block-list forms as `globs:`; when BOTH keys are present on the same rule,
+ * `globs:` wins silently and `paths:` is discarded (no merge, no warning —
+ * see module doc). The returned shape is unchanged either way — callers never
+ * see which key produced the value. `meta` carries only the recognised scalar
+ * keys that were present, with type coercion applied:
+ *   - `alwaysApply`, `auto-generated` → boolean ('true'/'false')
+ *   - `confidence` → number (undefined when NaN)
+ *   - all other recognised keys → quote-stripped strings
+ * Unknown keys are ignored without error.
+ *
+ * A leading run of blank lines and/or single-line HTML comments (e.g. the
+ * vendoring pipeline's provenance header) is tolerated before the opening
+ * `---` — see `stripLeadingProvenanceHeader`. Files with no such header parse
+ * identically to before this tolerance was added.
+ *
+ * @param {string} contents - raw file contents
+ * @returns {{ globs: string[] | null, meta: Record<string, unknown> }}
+ */
+export function parseGlobsFrontmatter(contents) {
+  const match = FRONTMATTER_RE.exec(stripLeadingProvenanceHeader(contents));
+  if (!match) return { globs: null, meta: {} };
+
+  const fmText = match[1];
+  const lines = fmText.split(/\r?\n/);
+
+  let globsValue = null;
+  let pathsValue = null;
+  // Which sequence-value key ('globs' | 'paths') is currently accumulating
+  // block-style `  - value` lines, or null when not inside either block.
+  let activeSeqKey = null;
+  /** @type {Record<string, unknown>} */
+  const meta = {};
+
+  for (const line of lines) {
+    const rstripped = line.replace(/\s+$/, '');
+
+    // Skip blank lines and comments
+    if (rstripped === '' || /^\s*#/.test(rstripped)) {
+      // If inside a `globs:`/`paths:` block, a blank line ends the sequence
+      // only if the next non-blank line is at col 0 (a new key). We just keep
+      // activeSeqKey set until we hit a non-indented non-blank line.
+      continue;
+    }
+
+    if (activeSeqKey) {
+      // Inside a `globs:`/`paths:` block — expect `  - value` indented lines
+      const seqMatch = rstripped.match(/^(\s+)-\s+(.*)/);
+      if (seqMatch) {
+        const raw = seqMatch[2].trim().replace(/^["']|["']$/g, '');
+        if (activeSeqKey === 'globs') {
+          if (!Array.isArray(globsValue)) globsValue = [];
+          globsValue.push(raw);
+        } else {
+          if (!Array.isArray(pathsValue)) pathsValue = [];
+          pathsValue.push(raw);
+        }
+        continue;
+      }
+      // Non-indented line — end of the sequence block
+      activeSeqKey = null;
+    }
+
+    // Top-level key detection
+    if (/^\s/.test(rstripped)) {
+      // Indented but not in a known block — skip (another block's continuation)
+      continue;
+    }
+
+    const colonIdx = rstripped.indexOf(':');
+    if (colonIdx === -1) {
+      throw new Error(`Malformed frontmatter line: ${JSON.stringify(rstripped)}`);
+    }
+
+    const key = rstripped.slice(0, colonIdx).trim();
+    const valuePart = rstripped.slice(colonIdx + 1).trim();
+
+    if (key === 'globs' || key === 'paths') {
+      let parsedValue;
+      if (valuePart === '') {
+        // Block-style list follows
+        activeSeqKey = key;
+        parsedValue = [];
+      } else if (valuePart.startsWith('[') && valuePart.endsWith(']')) {
+        // Flow-style: globs: ["src/**", "lib/**"] (or paths: [...])
+        const inner = valuePart.slice(1, -1).trim();
+        parsedValue = inner === ''
+          ? []
+          : inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, ''));
+      } else {
+        // Single inline value (unusual but handle gracefully)
+        parsedValue = [valuePart.replace(/^["']|["']$/g, '')];
+      }
+      if (key === 'globs') globsValue = parsedValue;
+      else pathsValue = parsedValue;
+    } else if (SCALAR_META_KEYS.has(key)) {
+      // Scalar activation key (issue #694). Strip surrounding quotes, then
+      // apply per-key coercion. Empty values are skipped (key not present).
+      const stripped = valuePart.replace(/^["']|["']$/g, '');
+      if (stripped === '') continue;
+      if (key === 'alwaysApply' || key === 'auto-generated') {
+        if (stripped === 'true') meta[key] = true;
+        else if (stripped === 'false') meta[key] = false;
+        // Any other value: leave undefined (not a recognised boolean)
+      } else if (key === 'confidence') {
+        const n = Number(stripped);
+        if (!Number.isNaN(n)) meta[key] = n;
+      } else {
+        meta[key] = stripped;
+      }
+    }
+    // Ignore all other keys
+  }
+
+  // Precedence (issue #795): `globs:` wins silently when both keys are present.
+  const globs = globsValue !== null ? globsValue : pathsValue;
+
+  return { globs, meta };
+}
+
+/**
+ * Maps the raw (hyphenated) frontmatter meta keys onto the camelCase RuleEntry
+ * field names, including only keys that were actually present.
+ *
+ * @param {Record<string, unknown>} meta
+ * @returns {Record<string, unknown>}
+ */
+function metaToEntryFields(meta) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  if (Object.prototype.hasOwnProperty.call(meta, 'description')) out.description = meta.description;
+  if (Object.prototype.hasOwnProperty.call(meta, 'mode')) out.mode = meta.mode;
+  if (Object.prototype.hasOwnProperty.call(meta, 'host-class')) out.hostClass = meta['host-class'];
+  if (Object.prototype.hasOwnProperty.call(meta, 'alwaysApply')) out.alwaysApply = meta.alwaysApply;
+  if (Object.prototype.hasOwnProperty.call(meta, 'expires-at')) out.expiresAt = meta['expires-at'];
+  if (Object.prototype.hasOwnProperty.call(meta, 'learning-key')) out.learningKey = meta['learning-key'];
+  if (Object.prototype.hasOwnProperty.call(meta, 'auto-generated')) out.autoGenerated = meta['auto-generated'];
+  if (Object.prototype.hasOwnProperty.call(meta, 'confidence')) out.confidence = meta.confidence;
+  if (Object.prototype.hasOwnProperty.call(meta, 'tier')) out.tier = meta.tier;
+  return out;
+}
+
+/**
+ * Deterministic gating check (issue #694 + #692). Returns `{ excluded: boolean,
+ * reason?: string }`. Applied to BOTH always-on and glob-matched rules.
+ *
+ * @param {Record<string, unknown>} meta - raw parsed meta (hyphenated keys)
+ * @param {string} filePath - absolute path (for WARN messages)
+ * @param {string|null} mode
+ * @param {string|null} hostClass
+ * @param {number} now - epoch ms
+ * @param {string|null} [context] - 'wave' | 'coordinator' | null (null = no tier gating)
+ * @returns {{ excluded: boolean }}
+ */
+function applyGates(meta, filePath, mode, hostClass, now, context = null) {
+  // Expiry gate — fail-open on a malformed `expires-at`.
+  if (Object.prototype.hasOwnProperty.call(meta, 'expires-at')) {
+    const rawExpiry = meta['expires-at'];
+    const ts = Date.parse(String(rawExpiry));
+    if (Number.isNaN(ts)) {
+      process.stderr.write(
+        `[rule-loader] Rule ${filePath} has unparseable expires-at ${JSON.stringify(rawExpiry)} — ignoring expiry\n`,
+      );
+    } else if (ts < now) {
+      process.stderr.write(
+        `[rule-loader] Rule ${filePath} expired at ${rawExpiry} — excluded\n`,
+      );
+      return { excluded: true };
+    }
+  }
+
+  // Mode gate — only active when a non-null `mode` param is supplied AND the
+  // rule declares a differing `mode`.
+  if (mode !== null && Object.prototype.hasOwnProperty.call(meta, 'mode') && meta.mode !== mode) {
+    return { excluded: true };
+  }
+
+  // Host-class gate — symmetric to the mode gate.
+  if (
+    hostClass !== null &&
+    Object.prototype.hasOwnProperty.call(meta, 'host-class') &&
+    meta['host-class'] !== hostClass
+  ) {
+    return { excluded: true };
+  }
+
+  // Tier gate (issue #692) — only active when context is non-null.
+  // BACKWARD-COMPAT: context === null → no tier gating whatsoever.
+  if (context !== null && Object.prototype.hasOwnProperty.call(meta, 'tier')) {
+    const tier = meta.tier;
+    if (context === 'wave' && tier === 'coordinator-only') {
+      return { excluded: true };
+    }
+    if (context === 'coordinator' && tier === 'wave-only') {
+      return { excluded: true };
+    }
+  }
+
+  return { excluded: false };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} RuleEntry
+ * @property {string} path - absolute path to the rule file
+ * @property {string} content - raw file contents (byte-identical to disk)
+ * @property {boolean} alwaysOn - true when neither `globs:` nor its `paths:`
+ *   alias (issue #795) frontmatter is present (UNCHANGED semantics; DISTINCT
+ *   from the `alwaysApply` frontmatter key)
+ * @property {string[]} matchedGlobs - globs that matched; empty when alwaysOn
+ * @property {true} [_parseError] - present only on frontmatter parse-error entries
+ * @property {string} [description] - frontmatter `description` (issue #694), when present
+ * @property {string} [mode] - frontmatter `mode` (issue #694), when present
+ * @property {string} [hostClass] - frontmatter `host-class` (issue #694), when present
+ * @property {boolean} [alwaysApply] - frontmatter `alwaysApply` (issue #694), when present
+ * @property {string} [expiresAt] - frontmatter `expires-at` ISO date (issue #694), when present
+ * @property {string} [learningKey] - frontmatter `learning-key` (issue #694), when present
+ * @property {boolean} [autoGenerated] - frontmatter `auto-generated` (issue #694), when present
+ * @property {number} [confidence] - frontmatter `confidence` (issue #694), when present
+ * @property {string} [tier] - frontmatter `tier` (issue #692): 'coordinator-only' | 'wave-only' | 'always', when present
+ */
+
+/**
+ * Loads rule files from `rulesDir` and returns those applicable to the given
+ * `scopePaths` and activation axes.
+ *
+ * Rules without `globs:` (or its `paths:` alias — issue #795) frontmatter are
+ * always included (alwaysOn: true). Rules with `globs:`/`paths:` are included
+ * only when at least one scopePath matches at least one glob pattern.
+ *
+ * After a successful frontmatter parse, deterministic gates (issue #694) are
+ * applied to BOTH always-on and glob-matched rules — a rule must pass ALL
+ * active gates (expiry + mode + host-class) to be included. The new params are
+ * strictly optional and default to "no gating", so the issue #336 two-key call
+ * shape stays 100% backward-compatible.
+ *
+ * On frontmatter parse error, the rule is treated as always-on and a warning
+ * is emitted to stderr — rules are never silently dropped. (Parse-error rules
+ * carry no meta, so they pass every gate.)
+ *
+ * @param {object} opts
+ * @param {string} opts.rulesDir - absolute path to the directory containing rule *.md files
+ * @param {string[]} [opts.scopePaths] - paths (relative to repo root) to match against globs
+ * @param {string|null} [opts.mode] - when non-null, exclude rules whose `mode` differs
+ * @param {string|null} [opts.hostClass] - when non-null, exclude rules whose `host-class` differs
+ * @param {number} [opts.now] - epoch ms used for expiry gating (injectable for tests)
+ * @param {string|null} [opts.context] - 'wave' | 'coordinator' | null; when non-null, applies
+ *   tier gating: 'wave' excludes coordinator-only rules, 'coordinator' excludes wave-only rules.
+ *   null (default) disables tier gating entirely — backward-compatible with all existing callers.
+ * @returns {RuleEntry[]}
+ */
+export function loadApplicableRules({
+  rulesDir,
+  scopePaths = [],
+  mode = null,
+  hostClass = null,
+  now = Date.now(),
+  context = null,
+}) {
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = readdirSync(rulesDir);
+  } catch (err) {
+    process.stderr.write(`[rule-loader] Cannot read rulesDir ${rulesDir}: ${err.message}\n`);
+    return [];
+  }
+
+  // Normalize scopePaths to forward slashes for consistent matching
+  const normalizedScope = scopePaths.map((p) => p.replace(/\\/g, '/'));
+
+  /** @type {RuleEntry[]} */
+  const results = [];
+
+  for (const entry of entries) {
+    if (extname(entry) !== '.md') continue;
+
+    const filePath = join(rulesDir, entry);
+    let content;
+
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch (err) {
+      process.stderr.write(`[rule-loader] Cannot read ${filePath}: ${err.message}\n`);
+      continue;
+    }
+
+    let globs;
+    let meta;
+    let parseError = false;
+
+    try {
+      ({ globs, meta } = parseGlobsFrontmatter(content));
+    } catch (err) {
+      process.stderr.write(
+        `[rule-loader] Frontmatter parse error in ${filePath}: ${err.message} — treating as always-on\n`,
+      );
+      globs = null;
+      meta = {};
+      parseError = true;
+    }
+
+    // Deterministic gating (issue #694 + #692) — applies to BOTH always-on and
+    // glob-matched candidates. Parse-error rules carry empty meta, so they pass
+    // every gate (preserving fail-open behavior).
+    if (!parseError && applyGates(meta, filePath, mode, hostClass, now, context).excluded) {
+      continue;
+    }
+
+    // Camel-cased meta fields surfaced on the entry (only present keys).
+    const metaFields = metaToEntryFields(meta);
+
+    if (globs === null) {
+      // No globs frontmatter (or parse error) → always-on
+      results.push({
+        path: filePath,
+        content,
+        alwaysOn: true,
+        matchedGlobs: [],
+        ...metaFields,
+        ...(parseError ? { _parseError: true } : {}),
+      });
+      continue;
+    }
+
+    if (globs.length === 0) {
+      // Empty globs array: matches nothing (intentionally scoped out)
+      continue;
+    }
+
+    // Check whether any scopePath matches any glob
+    const matchedGlobs = [];
+    for (const glob of globs) {
+      const matched = normalizedScope.some((sp) => matchGlob(sp, glob));
+      if (matched) {
+        matchedGlobs.push(glob);
+      }
+    }
+
+    if (matchedGlobs.length > 0) {
+      results.push({
+        path: filePath,
+        content,
+        alwaysOn: false,
+        matchedGlobs,
+        ...metaFields,
+      });
+    }
+  }
+
+  return results;
+}