session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/reconcile/verdict-ledger.mjs

@@ -0,0 +1,224 @@
+/**
+ * verdict-ledger.mjs — append-only record of reconcile verdicts and runs (#1710).
+ *
+ * The idempotency sidecar (`.orchestrator/runtime/reconcile-candidates.jsonl`,
+ * `./idempotency.mjs`) is gitignored and resolved per checkout, so a fresh git
+ * worktree or another host starts without it: an operator's explicit
+ * `rejected` verdict was lost there and `/reconcile` re-proposed the declined
+ * rule, while the session-start nudge reported "no reconcile run on record".
+ *
+ * This ledger lives at `.orchestrator/metrics/reconcile-verdicts.jsonl` under
+ * `resolveEventsLedgerRoot(repoRoot)` — a linked worktree maps to its MAIN
+ * checkout — beside `learnings.jsonl`, so it shares learnings' tracking status
+ * in every repo (tracked + `merge=union` in the vault, host-local here). It is
+ * NEVER rewritten, only appended. Two record shapes, one JSON object per line:
+ *   { kind: 'verdict', learning_key, outcome, processed_at, recorded_at }
+ *   { kind: 'run', at, learnings }   (`learnings`: count the run loaded; optional on older lines)
+ *
+ * Verdict lines carry DECISIONS only (see {@link BRANCH_SCOPED_OUTCOMES}): an
+ * outcome that describes one branch's tree (`written`, `already-on-disk`, or no
+ * outcome at all) already has a cross-tree witness in the tracked rule file's
+ * provenance marker, and mirroring it from a worktree whose branch is later
+ * abandoned would make the learning permanently non-re-proposable in main.
+ * Run recency (`lastRunAt`) comes from `run` lines only — a verdict is not a run.
+ *
+ * Writes happen ONLY for an explicit non-empty `repoRoot` — never a
+ * `process.cwd()` fallback, so a test without a root can never append to this
+ * repo's real ledger. Readers without a root return the empty result.
+ *
+ * Ceiling (BV-004): no lock. Concurrent worktree sessions append through
+ * O_APPEND with small lines (one `appendFileSync` per call), which keeps lines
+ * whole in practice; the sidecar stays the checkout-local work queue and this
+ * file only carries terminality and run recency. Revisit trigger: an
+ * interleaved or garbled ledger line observed (`skipped > 0` on a ledger no
+ * human edited).
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { resolveEventsLedgerRoot } from '../platform.mjs';
+
+/** Repo-relative location of the verdict ledger (resolved against the MAIN checkout). */
+export const VERDICT_LEDGER_PATH = '.orchestrator/metrics/reconcile-verdicts.jsonl';
+
+/**
+ * Terminal outcomes that describe ONE branch's tree, not a decision, and are
+ * therefore never mirrored into the ledger: `written` (writer.mjs persisted the
+ * rule file), `already-on-disk` (engine.mjs found its provenance marker) and the
+ * empty string (a record without `outcome` — pre-#1042, read as `written`). Every
+ * other outcome is a decision (today `rejected`, `expired-swept`).
+ */
+export const BRANCH_SCOPED_OUTCOMES = Object.freeze(new Set(['', 'written', 'already-on-disk']));
+
+/**
+ * @param {unknown} outcome - a sidecar record's `outcome` (absent/null ⇒ branch-scoped).
+ * @returns {boolean} true iff the outcome is a decision the ledger carries.
+ */
+export function isDecisionOutcome(outcome) {
+  return typeof outcome === 'string' && !BRANCH_SCOPED_OUTCOMES.has(outcome);
+}
+
+/**
+ * @param {unknown} repoRoot
+ * @returns {string|null} absolute ledger path, or null without an explicit root
+ */
+function ledgerPathFor(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
+  return join(resolveEventsLedgerRoot(repoRoot), VERDICT_LEDGER_PATH);
+}
+
+/**
+ * @typedef {Object} VerdictLedger
+ * @property {Map<string, string>} terminalKeys - learning_key → outcome of its first recorded verdict.
+ * @property {string|null} lastRunAt - max over run records' `at`, ISO (a verdict is not a run).
+ * @property {number|null} lastRunLearnings - `learnings` of the run record with the latest `at`;
+ *   null when that record (or every run record) predates the field or carries no valid integer.
+ * @property {number} skipped - lines that were not a valid verdict/run record (counted, never silent).
+ * @property {boolean} present - the file was read.
+ * @property {boolean} readError - the file exists (or may) but could not be read (non-ENOENT).
+ */
+
+/** @returns {VerdictLedger} */
+function emptyLedger() {
+  return {
+    terminalKeys: new Map(),
+    lastRunAt: null,
+    lastRunLearnings: null,
+    skipped: 0,
+    present: false,
+    readError: false,
+  };
+}
+
+/** `<path>\0<skipped>` pairs already warned about in this process. */
+const warnedSkipped = new Set();
+
+/**
+ * Load the verdict ledger for `repoRoot`. A missing file (ENOENT) is the empty
+ * result, silently; any other read failure is the empty result plus ONE stderr
+ * WARN with `readError: true` (same split as `defaultLoadLearnings`). Blank lines
+ * are ignored; every other line that is not a valid verdict/run record is
+ * counted in `skipped`, and a non-zero count emits ONE stderr WARN naming the
+ * path and the count — once per path and count per process (no production
+ * caller reads `skipped`). Never throws.
+ *
+ * @param {string|undefined} repoRoot - explicit root; absent → empty result.
+ * @returns {VerdictLedger}
+ */
+export function loadVerdictLedger(repoRoot) {
+  const result = emptyLedger();
+  const absPath = ledgerPathFor(repoRoot);
+  if (absPath === null) return result;
+
+  let raw;
+  try {
+    raw = readFileSync(absPath, 'utf8');
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      result.readError = true;
+      process.stderr.write(
+        `⚠ loadVerdictLedger: cannot read ${absPath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — treating as EMPTY\n`,
+      );
+    }
+    return result;
+  }
+  result.present = true;
+
+  let maxMs = -Infinity;
+  let latestRunMs = -Infinity;
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let rec;
+    try {
+      rec = JSON.parse(trimmed);
+    } catch {
+      result.skipped += 1;
+      continue;
+    }
+    if (rec && rec.kind === 'verdict' && typeof rec.learning_key === 'string' && rec.learning_key.length > 0) {
+      if (!result.terminalKeys.has(rec.learning_key)) {
+        result.terminalKeys.set(rec.learning_key, typeof rec.outcome === 'string' ? rec.outcome : '');
+      }
+    } else if (rec && rec.kind === 'run' && typeof rec.at === 'string' && Number.isFinite(Date.parse(rec.at))) {
+      const t = Date.parse(rec.at);
+      if (t > maxMs) maxMs = t;
+      if (t >= latestRunMs) {
+        latestRunMs = t;
+        result.lastRunLearnings =
+          Number.isSafeInteger(rec.learnings) && rec.learnings >= 0 ? rec.learnings : null;
+      }
+    } else {
+      result.skipped += 1;
+    }
+  }
+  if (maxMs > -Infinity) result.lastRunAt = new Date(maxMs).toISOString();
+  // Once per path and count per process: one /reconcile reads the ledger once per
+  // stamp, and the same bad line must not print N+2 identical warnings.
+  const warnKey = `${absPath}\0${result.skipped}`;
+  if (result.skipped > 0 && !warnedSkipped.has(warnKey)) {
+    warnedSkipped.add(warnKey);
+    process.stderr.write(
+      `⚠ loadVerdictLedger: ${result.skipped} line(s) in ${absPath} are not a valid verdict/run record — ignored\n`,
+    );
+  }
+  return result;
+}
+
+/**
+ * Append all `records` as JSONL in ONE write (mkdir -p first). Never throws.
+ * @param {string|undefined} repoRoot
+ * @param {Array<Record<string, unknown>>} records
+ * @returns {{ ok: boolean, appended: number, error?: string }}
+ */
+function appendRecords(repoRoot, records) {
+  const absPath = ledgerPathFor(repoRoot);
+  if (absPath === null) return { ok: false, appended: 0, error: 'no repoRoot' };
+  if (records.length === 0) return { ok: true, appended: 0 };
+  try {
+    mkdirSync(dirname(absPath), { recursive: true });
+    appendFileSync(absPath, records.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf8');
+    return { ok: true, appended: records.length };
+  } catch (err) {
+    return { ok: false, appended: 0, error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Append one verdict line per terminal candidate (`processed_at` set). The
+ * caller decides which records are new; this function does not dedupe.
+ *
+ * @param {string|undefined} repoRoot - explicit root; absent → nothing written.
+ * @param {Array<{ learning_key?: unknown, outcome?: unknown, processed_at?: unknown }>} candidates
+ * @param {string} [recordedAt] - ISO; defaults to now.
+ * @returns {{ ok: boolean, appended: number, error?: string }}
+ */
+export function appendVerdicts(repoRoot, candidates, recordedAt) {
+  const at = typeof recordedAt === 'string' && recordedAt.length > 0 ? recordedAt : new Date().toISOString();
+  const records = (Array.isArray(candidates) ? candidates : [])
+    .filter((c) => c && typeof c.learning_key === 'string' && c.learning_key.length > 0 && typeof c.processed_at === 'string')
+    .map((c) => ({
+      kind: 'verdict',
+      learning_key: c.learning_key,
+      outcome: typeof c.outcome === 'string' ? c.outcome : '',
+      processed_at: c.processed_at,
+      recorded_at: at,
+    }));
+  return appendRecords(repoRoot, records);
+}
+
+/**
+ * Append one run record.
+ * @param {string|undefined} repoRoot - explicit root; absent → nothing written.
+ * @param {string} at - ISO timestamp of the run.
+ * @param {number} [learnings] - how many learnings the run loaded; omitted from the
+ *   record unless a non-negative integer (the nudge's "new since last run" baseline).
+ * @returns {{ ok: boolean, appended: number, error?: string }}
+ */
+export function appendRun(repoRoot, at, learnings) {
+  const rec = { kind: 'run', at };
+  if (Number.isSafeInteger(learnings) && learnings >= 0) rec.learnings = learnings;
+  return appendRecords(repoRoot, [rec]);
+}

package/scripts/lib/reconcile-nudge-banner.mjs

@@ -35,8 +35,18 @@
  *     high-water mark across all runs to date), used for the "new learnings
  *     since last run" delta heuristic.
  * There is no separate `reconcile`-scoped event in `.orchestrator/metrics/events.jsonl`
- * — the idempotency sidecar IS the durable run record, so this module reads
- * that directly rather than re-deriving a signal from the generic event log.
+ * — the idempotency sidecar is the durable checkout-local run record, so this
+ * module reads that directly rather than re-deriving a signal from the generic
+ * event log. Since #1710 a second, checkout-independent run record exists: the
+ * append-only verdict ledger (`./reconcile/verdict-ledger.mjs`, main checkout
+ * via `resolveEventsLedgerRoot`). Its `run` lines carry `at` and the number of
+ * learnings that run loaded; the ledger's run recency comes from those `run`
+ * lines ONLY (a verdict line is not a run — a ledger holding only hand stamps or
+ * `sweep-expired-rules --apply` verdicts reports no run, so rule (a) says so
+ * honestly instead of rule (b) counting every learning as new). `lastRunAt` is
+ * the later of both sources and the delta baseline is the larger of the sidecar
+ * row count and that learnings count, so a fresh worktree without the sidecar
+ * still sees the run.
  *
  * Reuses the existing learnings-corpus helpers rather than re-implementing
  * filter logic:
@@ -72,12 +82,13 @@
  *  - Issue #723.
  */
 
-import { join } from 'node:path';
 
+import { resolveLedgerPath } from './ledger-path.mjs';
 import { readLearnings } from './learnings/io.mjs';
 import { surfaceTopN } from './learnings/surface.mjs';
 import { countReconcileBacklog } from './reconcile/backlog.mjs';
 import { loadCandidates } from './reconcile/idempotency.mjs';
+import { loadVerdictLedger } from './reconcile/verdict-ledger.mjs';
 import { readConfigFile } from './config/io.mjs';
 import { _parseReconcile } from './config/reconcile.mjs';
 
@@ -169,6 +180,17 @@ function _lastRunAt(candidates) {
   return Number.isFinite(maxMs) && maxMs > -Infinity ? new Date(maxMs).toISOString() : null;
 }
 
+/**
+ * @param {string|null} a - ISO timestamp or null
+ * @param {string|null} b - ISO timestamp or null
+ * @returns {string|null} the later of the two, or null when both are null
+ */
+function _laterIso(a, b) {
+  if (a === null) return b;
+  if (b === null) return a;
+  return Date.parse(b) > Date.parse(a) ? b : a;
+}
+
 /**
  * Pure computation — always returns the full shape (never null, never throws).
  * Touches disk only via the injected/default learnings + candidates readers,
@@ -215,7 +237,7 @@ export async function computeReconcileNudge(opts = {}) {
   };
 
   const repoRoot = typeof opts.repoRoot === 'string' && opts.repoRoot.length > 0 ? opts.repoRoot : process.cwd();
-  const learningsPath = join(repoRoot, LEARNINGS_PATH);
+  const learningsPath = resolveLedgerPath(LEARNINGS_PATH, repoRoot);
 
   /** @type {object[]} */
   let entries;
@@ -282,6 +304,9 @@ export async function computeReconcileNudge(opts = {}) {
   // sentence (HR-106). `repoRoot` stays required — the sidecar and the
   // `.claude/rules/` provenance scan are resolved from it.
   // Never throws (all-zero on failure).
+  // #1710 — the append-only verdict ledger (main checkout, outlives the
+  // checkout-local sidecar) is read ONCE and handed to the count as well.
+  const ledger = loadVerdictLedger(repoRoot);
   const {
     eligible: eligibleCount,
     alreadyMaterialized,
@@ -290,12 +315,21 @@ export async function computeReconcileNudge(opts = {}) {
     repoRoot,
     learnings: entries,
     ...(candidatesRead ? { existingCandidates: candidates } : {}),
+    ledgerKeys: ledger.terminalKeys,
     now: opts.now,
     minInsightChars,
   });
 
-  const lastRunAt = _lastRunAt(candidates);
-  const lastRunCandidateCount = Array.isArray(candidates) ? candidates.length : 0;
+  // The later of the sidecar's and the ledger's run evidence: a fresh worktree
+  // has no sidecar, yet the run on record in the ledger is still a run.
+  const lastRunAt = _laterIso(_lastRunAt(candidates), ledger.lastRunAt);
+  // The ledger's run record carries the learnings count that run saw, so a
+  // fresh worktree (no sidecar) does not report every learning as new. The max
+  // keeps the main checkout's delta unchanged — never larger than before.
+  const lastRunCandidateCount = Math.max(
+    Array.isArray(candidates) ? candidates.length : 0,
+    ledger.lastRunLearnings ?? 0,
+  );
   const delta = entries.length - lastRunCandidateCount;
   const quarantined = typeof skippedCandidates === 'number' ? skippedCandidates : 0;
 

package/scripts/lib/resource-probe/evaluate.mjs

@@ -26,8 +26,16 @@
  *      number"), one noting "five consecutive sessions wrongly capped at 2".
  *   2. `concurrent-sessions-warn` is named for SESSIONS but was compared against
  *      `claude_processes_count`. Measured ratio processes:sessions = 6.0. That
- *      threshold fired on 93.6% of starts; against the real peer count it fires
- *      on 4.2%.
+ *      threshold fired on 93.6% of starts; against the real peer count it fired
+ *      on 4.2% (2026-08-21). That rate did not hold: re-measured 2026-10-17 over
+ *      starts since 2026-08-24, `peer_count >= 5` fires on 880/1305 = 67.4%
+ *      (M4) and 255/991 = 25.7% (M5) — #1650. The session-start banner's WARN
+ *      icon was re-aimed to a start wave (`hooks/on-session-start.mjs`,
+ *      START_WAVE_*). #1654 finished the re-aim here: a state present on two
+ *      thirds of M4 starts is a standing condition, and HR-104 forbids letting
+ *      one count as a second opinion. concurrencySignal() below therefore still
+ *      REPORTS the peer count (an `info:` reason) but no longer contributes a
+ *      soft signal — neither the registry branch nor the process fallback.
  *   3. Any ONE soft signal capped agents-per-wave at 2 outright, so the union of
  *      three noisy axes decided wave size on its noisiest member.
  *
@@ -51,6 +59,8 @@
  *     when present. `claude_processes_count` survives only as a fallback, scaled
  *     by the measured PROCESSES_PER_SESSION factor so the configured threshold
  *     keeps meaning "sessions" on hosts where the registry is unavailable.
+ *     Since #1654 the concurrency axis is REPORT-ONLY: it never enters
+ *     `signals.soft`, so it can neither cap alone nor pair into a cap.
  *   - TWO-SIGNAL RULE: a single soft signal is informational — reported in
  *     `reasons`, capping nothing. A cap needs two INDEPENDENT soft signals
  *     agreeing, or one hard signal. Simulated on the same 1477-sample corpus:
@@ -219,12 +229,24 @@ function memorySignal(snapshot, ramMin, ramCrit) {
 }
 
 /**
- * Resolve the concurrency signal, preferring the live session registry count
+ * Resolve the concurrency report, preferring the live session registry count
  * over the raw process count. Returns `null` when neither is available.
  *
+ * REPORT-ONLY since #1654: `soft` is always `false`. The peer count is a
+ * standing condition, not live load — `peer_count >= 5` held on 880/1305 =
+ * 67.4% of M4 and 255/991 = 25.7% of M5 starts since 2026-08-24 (#1650,
+ * re-measured 2026-10-17: 78/115 = 67.8% M4). HR-104: a usually-present signal
+ * reports and NEVER counts as a second opinion, so letting it pair with one
+ * real soft signal would restore the one-signal cap under a two-signal name
+ * (the same defect zombies had). The rare, decision-changing concurrency signal
+ * is the start wave in `hooks/on-session-start.mjs` (START_WAVE_*), which is
+ * not a snapshot field. The process-count fallback measures the same standing
+ * state and is report-only for the same reason.
+ *
  * @param {object} snapshot
  * @param {number} concWarn — configured threshold, denominated in SESSIONS
- * @returns {{soft: boolean, reason: string|null}|null}
+ * @returns {{soft: false, reason: string|null}|null} — `reason` set when the
+ *   threshold is reached (caller reports it as `info:`); never a soft signal.
  */
 function concurrencySignal(snapshot, concWarn) {
   const { peer_sessions_count, claude_processes_count } = snapshot;
@@ -234,7 +256,7 @@ function concurrencySignal(snapshot, concWarn) {
   if (hasPeers) {
     if (peer_sessions_count >= concWarn) {
       return {
-        soft: true,
+        soft: false,
         reason: `${peer_sessions_count} peer session(s) live in the registry (threshold: ${concWarn}) — consider sequencing this session after others finish.`,
       };
     }
@@ -252,7 +274,7 @@ function concurrencySignal(snapshot, concWarn) {
   const procThreshold = concWarn * PROCESSES_PER_SESSION;
   if (claude_processes_count >= procThreshold) {
     return {
-      soft: true,
+      soft: false,
       reason: `${claude_processes_count} Claude processes running (fallback threshold ${procThreshold} = ${concWarn} sessions × ${PROCESSES_PER_SESSION} processes/session; the live session registry was unavailable).`,
     };
   }
@@ -339,10 +361,11 @@ export function evaluate(snapshot, thresholds, options = {}) {
   }
 
   // --- Concurrency axis: registry sessions, not raw process count -----------
+  // REPORT-ONLY (#1654): a standing condition on 67.4% of M4 starts must not
+  // become the second signal that caps a wave (HR-104, see concurrencySignal).
   const conc = concurrencySignal(snapshot, concWarn);
-  if (conc && conc.soft) {
-    softSignals.push('concurrency');
-    reasons.push(conc.reason);
+  if (conc && conc.reason) {
+    reasons.push(`info: ${conc.reason} Not counted as a capacity signal (standing condition, #1654).`);
   }
 
   // --- Swap: only meaningful when the memory signal is NOT healthy ----------

package/scripts/lib/resource-probe/probe-platform.mjs

@@ -306,7 +306,9 @@ export async function ramAvailableGb() {
  * #1089 the threshold was compared against `claude_processes_count` instead —
  * a measured 6x unit error (median processes:sessions = 6.0 over 1461 paired
  * samples), which is why a threshold of 5 fired on 93.6% of session starts
- * while the same threshold against the real count fires on 4.2%.
+ * while the same threshold against the real count fired on 4.2% at the time.
+ * Re-measured 2026-10-17 (#1650) it fires on 67.4% (M4) / 25.7% (M5) — a
+ * standing signal (HR-101), so the banner icon follows a start wave instead.
  *
  * Semantics mirror `detectPeers()` exactly: EXCLUDES the calling session and
  * counts only entries whose `last_heartbeat` is within `freshnessMin` minutes.

package/scripts/lib/rule-loader.mjs

@@ -203,8 +203,8 @@ function unquoteYamlScalar(valuePart) {
  * its `paths:` alias (issue #795), and the scalar activation keys (issue #694).
  *
  * Returns:
- *   - `{ globs: string[] | null, meta: object }` on success
- *   - `{ globs: null, meta: {}, defect: 'frontmatter-not-at-top' }` when a
+ *   - `{ globs: string[] | null, paths: string[] | null, meta: object }` on success
+ *   - `{ globs: null, paths: null, meta: {}, defect: 'frontmatter-not-at-top' }` when a
  *     frontmatter block exists but does not start on line 1 (#1449)
  *   - throws `Error` on malformed frontmatter so the caller can fall back
  *
@@ -212,8 +212,11 @@ function unquoteYamlScalar(valuePart) {
  * 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
+ * see module doc). `globs` never tells callers which key produced the value;
+ * the additive `paths` field does carry the raw `paths:` list on its own
+ * (`null` when the key is absent), because Claude Code reads ONLY `paths:` and
+ * ignores `globs:` (#1638) — a caller asking "what does Claude Code scope?"
+ * needs that key alone, not the merged 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)
@@ -226,15 +229,15 @@ function unquoteYamlScalar(valuePart) {
  * the `defect` field names the misplacement (see {@link FRONTMATTER_NOT_AT_TOP}).
  *
  * @param {string} contents - raw file contents
- * @returns {{ globs: string[] | null, meta: Record<string, unknown>, defect?: 'frontmatter-not-at-top' }}
+ * @returns {{ globs: string[] | null, paths: string[] | null, meta: Record<string, unknown>, defect?: 'frontmatter-not-at-top' }}
  */
 export function parseGlobsFrontmatter(contents) {
   const match = FRONTMATTER_RE.exec(contents);
   if (match) return parseFrontmatterBlock(match[1]);
   if (hasDisplacedFrontmatter(contents)) {
-    return { globs: null, meta: {}, defect: FRONTMATTER_NOT_AT_TOP };
+    return { globs: null, paths: null, meta: {}, defect: FRONTMATTER_NOT_AT_TOP };
   }
-  return { globs: null, meta: {} };
+  return { globs: null, paths: null, meta: {} };
 }
 
 /**
@@ -274,7 +277,7 @@ function hasDisplacedFrontmatter(contents) {
  * Throws on a malformed top-level line — see {@link parseGlobsFrontmatter}.
  *
  * @param {string} fmText - frontmatter body without its fences
- * @returns {{ globs: string[] | null, meta: Record<string, unknown> }}
+ * @returns {{ globs: string[] | null, paths: string[] | null, meta: Record<string, unknown> }}
  */
 function parseFrontmatterBlock(fmText) {
   const lines = fmText.split(/\r?\n/);
@@ -370,7 +373,7 @@ function parseFrontmatterBlock(fmText) {
   // Precedence (issue #795): `globs:` wins silently when both keys are present.
   const globs = globsValue !== null ? globsValue : pathsValue;
 
-  return { globs, meta };
+  return { globs, paths: pathsValue, meta };
 }
 
 /**
@@ -565,6 +568,10 @@ function applyGates(meta, filePath, mode, hostClass, now, context = null) {
  * @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.
+ * @param {'merged'|'paths'} [opts.scopeKey] - which frontmatter key scopes a rule. 'merged'
+ *   (default) is this loader's own wave-injection semantics: `globs:`, else its `paths:` alias.
+ *   'paths' is Claude Code's native semantics (#1638): only `paths:` scopes, so a rule with
+ *   `globs:` but no `paths:` is always-on — Claude Code ignores `globs:` without an error.
  * @returns {RuleEntry[]}
  */
 export function loadApplicableRules({
@@ -574,6 +581,7 @@ export function loadApplicableRules({
   hostClass = null,
   now = Date.now(),
   context = null,
+  scopeKey = 'merged',
 }) {
   /** @type {string[]} */
   let entries;
@@ -622,7 +630,9 @@ export function loadApplicableRules({
     let parseError = false;
 
     try {
-      ({ globs, meta, defect } = parseGlobsFrontmatter(content));
+      const parsed = parseGlobsFrontmatter(content);
+      ({ meta, defect } = parsed);
+      globs = scopeKey === 'paths' ? parsed.paths : parsed.globs;
     } catch (err) {
       process.stderr.write(
         `[rule-loader] Frontmatter parse error in ${filePath}: ${err.message} — treating as always-on\n`,