session-orchestrator 5.2.0 → 5.4.0

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

@@ -45,6 +45,14 @@
  *   - `surfaceTopN` (`./learnings/surface.mjs`) — the canonical active-learning
  *     filter (confidence > floor, not expired); called with a large cap to get
  *     the full active set rather than a top-N slice.
+ *   - `countReconcileBacklog` (`./reconcile/backlog.mjs`) — the SAME eligibility +
+ *     materialization partition `/reconcile` applies, imported from the LEAF module
+ *     rather than from `./reconcile/engine.mjs`. The engine is WRITE-capable (it
+ *     merges the candidate store) and drags the emitter, renderer and unicode
+ *     validator behind it: importing the count from there took this probe's static
+ *     closure from 11 modules / 151,946 B to 19 / 322,897 B (+112 %, measured
+ *     2026-09-18), inherited unasked by `maintenance-due-banner.mjs`. A banner must
+ *     not be able to reach a writer.
  *   - `filterEligible` (`./reconcile/eligibility.mjs`) — the SAME type/file_paths
  *     allow-list gate the reconcile engine itself uses (deliberately NOT
  *     confidence-gated — mirrors `runReconcile`'s own posture, see
@@ -68,7 +76,7 @@ import { join } from 'node:path';
 
 import { readLearnings } from './learnings/io.mjs';
 import { surfaceTopN } from './learnings/surface.mjs';
-import { filterEligible } from './reconcile/eligibility.mjs';
+import { countReconcileBacklog } from './reconcile/backlog.mjs';
 import { loadCandidates } from './reconcile/idempotency.mjs';
 import { readConfigFile } from './config/io.mjs';
 import { _parseReconcile } from './config/reconcile.mjs';
@@ -82,9 +90,67 @@ export const NUDGE_MIN_LEARNINGS = 20;
 /** Nudge threshold (b): new learnings accrued since the last determinable reconcile run. */
 export const NUDGE_MIN_DELTA = 15;
 
-/** Nudge threshold (c): rule-eligible learnings (type + file_paths allow-list), regardless of confidence. */
+/**
+ * Nudge threshold (c): reconcile BACKLOG — rule-eligible learnings (type + file_paths
+ * allow-list, not expired, regardless of confidence) MINUS those already materialized
+ * in the idempotency sidecar or a `.claude/rules/` provenance marker. Counting the
+ * materialized ones too made the probe un-greenable (#1380: 98 eligible, 35 already
+ * materialized, and no `/reconcile` run could ever clear it).
+ */
 export const NUDGE_MIN_ELIGIBLE = 3;
 
+/**
+ * Resolve the `reconcile` Session Config settings this module needs, in ONE read.
+ *
+ * Both consumers go through here, so the nudge can never judge on a different
+ * population than `/reconcile` does: the skill reads `reconcile.min-insight-chars`
+ * (default 24) and forwards it to the engine, and so must this probe. Before #1380
+ * follow-up the value was only read AFTER the backlog had already been counted, which
+ * left the placeholder-insight gate practically OFF for the banner.
+ *
+ * Precedence: an injected already-parsed Session Config wins per KEY (DI seam, avoids a
+ * second CLAUDE.md read); any key it does not carry falls back to parsing
+ * CLAUDE.md/AGENTS.md; an unreadable config falls back to `_parseReconcile('')`, i.e.
+ * the parser's OWN documented defaults — never a literal repeated here.
+ *
+ * Never throws.
+ *
+ * @param {string} repoRoot
+ * @param {unknown} [config] already-parsed Session Config
+ * @returns {Promise<{enabled: boolean, minInsightChars: number}>}
+ */
+async function _resolveReconcileSettings(repoRoot, config) {
+  const injected =
+    config && typeof config === 'object' && /** @type {any} */ (config).reconcile &&
+    typeof (/** @type {any} */ (config).reconcile) === 'object'
+      ? /** @type {Record<string, unknown>} */ (/** @type {any} */ (config).reconcile)
+      : null;
+
+  const hasEnabled = injected !== null && typeof injected.enabled === 'boolean';
+  const hasChars = injected !== null && Number.isFinite(injected['min-insight-chars']);
+  if (hasEnabled && hasChars) {
+    return {
+      enabled: /** @type {boolean} */ (injected.enabled),
+      minInsightChars: Number(injected['min-insight-chars']),
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = _parseReconcile(await readConfigFile(repoRoot));
+  } catch {
+    // Config unreadable — take the parser's own defaults (single source of truth).
+    parsed = _parseReconcile('');
+  }
+
+  return {
+    enabled: hasEnabled ? /** @type {boolean} */ (injected.enabled) : parsed.enabled,
+    minInsightChars: hasChars
+      ? Number(injected['min-insight-chars'])
+      : parsed['min-insight-chars'],
+  };
+}
+
 /**
  * Resolve the max `created_at` across reconcile-candidate sidecar records —
  * the most recent reconcile run's timestamp, or `null` when no run is on
@@ -110,11 +176,19 @@ function _lastRunAt(candidates) {
  *
  * @param {object} [opts]
  * @param {string} [opts.repoRoot] — project root (defaults to process.cwd()).
- * @param {Date|number} [opts.now] — injectable clock, forwarded to the active-learning filter.
+ * @param {Date|number} [opts.now] — injectable clock, forwarded to the active-learning
+ *   filter AND the eligibility expiry gate.
+ * @param {number} [opts.minInsightChars] — forwarded to the eligibility filter. When
+ *   OMITTED the value is read from Session Config (`reconcile.min-insight-chars`,
+ *   default 24) rather than left inert, so the nudge and `/reconcile` count the SAME
+ *   population — see `_resolveReconcileSettings`.
+ * @param {object} [opts.config] — optional already-parsed Session Config (DI seam).
  * @returns {Promise<{
  *   totalLearnings: number,
  *   activeLearnings: number,
  *   eligibleCount: number,
+ *   alreadyMaterialized: number,
+ *   backlogCount: number,
  *   lastRunAt: string|null,
  *   lastRunCandidateCount: number,
  *   delta: number,
@@ -131,6 +205,8 @@ export async function computeReconcileNudge(opts = {}) {
     totalLearnings: 0,
     activeLearnings: 0,
     eligibleCount: 0,
+    alreadyMaterialized: 0,
+    backlogCount: 0,
     lastRunAt: null,
     lastRunCandidateCount: 0,
     delta: 0,
@@ -166,20 +242,29 @@ export async function computeReconcileNudge(opts = {}) {
 
   if (active.length === 0) return empty;
 
-  let eligibleCount;
-  try {
-    eligibleCount = filterEligible(entries).eligible.length;
-  } catch {
-    eligibleCount = 0;
-  }
+  // Same partition a real /reconcile run applies (engine.mjs step 3/3a) — one
+  // truth, so the nudge can only fire on work /reconcile is able to clear.
+  // That includes the placeholder-insight gate: when the caller did not supply
+  // `minInsightChars`, read it from Session Config BEFORE counting, or the
+  // banner counts learnings `/reconcile` would reject.
+  const minInsightChars = Number.isFinite(opts.minInsightChars)
+    ? Number(opts.minInsightChars)
+    : (await _resolveReconcileSettings(repoRoot, opts.config)).minInsightChars;
 
+  // The candidate store is read ONCE, BEFORE the backlog count — the count needs
+  // the same records for its sidecar-dedupe half, and reading them here lets it
+  // be handed down instead of read a second time (`candidatesRead` says whether
+  // the hand-down is trustworthy; on a failed read we hand nothing down and let
+  // `countReconcileBacklog` decide for itself rather than pass a fake empty set).
   /** @type {Array<Record<string, unknown>>} */
   let candidates;
   /** @type {number|undefined} */
   let skippedCandidates;
+  let candidatesRead = false;
   try {
     const diag = loadCandidates({ repoRoot });
     candidates = Array.isArray(diag?.records) ? diag.records : [];
+    candidatesRead = Array.isArray(diag?.records);
     // Absence-preserving, mirroring `engine.mjs` `summary.skipped`: only a
     // finite count means "the store was inspected". Absent ⇒ never checked,
     // 0 ⇒ checked and clean.
@@ -190,6 +275,25 @@ export async function computeReconcileNudge(opts = {}) {
     // fabricating a clean 0.
   }
 
+  // ONE corpus, ONE population. `entries` (read above via `readLearnings`) is
+  // handed down instead of letting the count re-read and re-normalize the same
+  // file: the banner line names `activeLearnings` and `backlogCount` side by
+  // side, and two independent reads of one file are two populations wearing one
+  // sentence (HR-106). `repoRoot` stays required — the sidecar and the
+  // `.claude/rules/` provenance scan are resolved from it.
+  // Never throws (all-zero on failure).
+  const {
+    eligible: eligibleCount,
+    alreadyMaterialized,
+    backlog: backlogCount,
+  } = countReconcileBacklog({
+    repoRoot,
+    learnings: entries,
+    ...(candidatesRead ? { existingCandidates: candidates } : {}),
+    now: opts.now,
+    minInsightChars,
+  });
+
   const lastRunAt = _lastRunAt(candidates);
   const lastRunCandidateCount = Array.isArray(candidates) ? candidates.length : 0;
   const delta = entries.length - lastRunCandidateCount;
@@ -213,15 +317,18 @@ export async function computeReconcileNudge(opts = {}) {
   if (lastRunAt !== null && delta > NUDGE_MIN_DELTA) {
     reasons.push(`${delta} new learnings since the last reconcile run`);
   }
-  // (c) — enough rule-eligible learnings to be worth a batch, independent of confidence.
-  if (eligibleCount >= NUDGE_MIN_ELIGIBLE) {
-    reasons.push(`${eligibleCount} rule-eligible learnings`);
+  // (c) — enough NOT-YET-MATERIALIZED rule-eligible learnings to be worth a
+  // batch, independent of confidence. HR-106: the reason names the number judged.
+  if (backlogCount >= NUDGE_MIN_ELIGIBLE) {
+    reasons.push(`${backlogCount} rule-eligible learnings awaiting a rule`);
   }
 
   const computed = {
     totalLearnings: entries.length,
     activeLearnings: active.length,
     eligibleCount,
+    alreadyMaterialized,
+    backlogCount,
     lastRunAt,
     lastRunCandidateCount,
     delta,
@@ -236,25 +343,6 @@ export async function computeReconcileNudge(opts = {}) {
   return computed;
 }
 
-/**
- * Best-effort extraction of `reconcile.enabled` from an already-parsed Session
- * Config object (DI/test seam — avoids re-reading CLAUDE.md when the caller
- * already has it). Returns `null` when unresolvable from `config` alone, in
- * which case `checkReconcileNudge` falls back to reading CLAUDE.md/AGENTS.md.
- *
- * @param {unknown} config
- * @returns {boolean|null}
- */
-function _reconcileEnabledFromConfig(config) {
-  if (config && typeof config === 'object') {
-    const rc = /** @type {Record<string, unknown>} */ (config).reconcile;
-    if (rc && typeof rc === 'object' && typeof (/** @type {any} */ (rc).enabled) === 'boolean') {
-      return /** @type {any} */ (rc).enabled;
-    }
-  }
-  return null;
-}
-
 /**
  * Check reconcile-nudge readiness and produce a session-start banner.
  *
@@ -274,26 +362,30 @@ export async function checkReconcileNudge(opts = {}) {
     const { repoRoot, config, now } = opts;
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
+    // ONE config read for both settings, BEFORE the backlog is counted — the
+    // `min-insight-chars` gate must reach `countReconcileBacklog`, and reading the
+    // config afterwards (as this did before) left it inert.
+    let reconcileEnabled = false;
+    let minInsightChars;
+    try {
+      ({ enabled: reconcileEnabled, minInsightChars } = await _resolveReconcileSettings(
+        repoRoot,
+        config,
+      ));
+    } catch {
+      // Unreachable in practice (_resolveReconcileSettings never throws) — keep the
+      // conservative default and let computeReconcileNudge resolve the gate itself.
+      reconcileEnabled = false;
+    }
+
     let computed;
     try {
-      computed = await computeReconcileNudge({ repoRoot, now });
+      computed = await computeReconcileNudge({ repoRoot, now, minInsightChars });
     } catch {
       return null;
     }
     if (!computed || computed.nudge !== true) return null;
 
-    let reconcileEnabled = _reconcileEnabledFromConfig(config);
-    if (reconcileEnabled === null) {
-      try {
-        const content = await readConfigFile(repoRoot);
-        reconcileEnabled = _parseReconcile(content).enabled;
-      } catch {
-        // Config unreadable — fall back to the documented config default (false)
-        // so the informational parenthetical still renders conservatively.
-        reconcileEnabled = false;
-      }
-    }
-
     // Three-state last-run label. `never` is a claim about history and must only
     // be made when the store was inspected and held nothing: a store whose lines
     // were quarantined by the shape guard is EVIDENCE OF A RUN that can no longer
@@ -323,7 +415,8 @@ export async function checkReconcileNudge(opts = {}) {
     }
 
     const lines = [
-      `⚠ reconcile-nudge: ${computed.activeLearnings} active learnings, ${computed.eligibleCount} rule-eligible, ` +
+      `⚠ reconcile-nudge: ${computed.activeLearnings} active learnings, ${computed.backlogCount} rule-eligible awaiting a rule ` +
+        `(${computed.alreadyMaterialized} already materialized), ` +
         `last reconcile run: ${lastRunLabel} — run /reconcile to convert learnings into rules.`,
     ];
     if (reconcileEnabled === false) {

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

@@ -30,6 +30,37 @@ export function parseEtimeToMinutes(etime) {
   return days * 24 * 60 + hours * 60 + mins;
 }
 
+/**
+ * Parse a `ps` etime field (`[[DD-]HH:]MM:SS`) into whole SECONDS.
+ *
+ * Twin of {@link parseEtimeToMinutes}, which drops the seconds field because
+ * minute resolution is all the zombie counter needs. The orphan reaper
+ * (`scripts/lib/orphan-reaper.mjs`) cannot use that: its minimum age is 300
+ * seconds and its identity check reconstructs a start time as
+ * `now - etimeSeconds * 1000`, where a discarded seconds field would be a
+ * systematic error of up to 59 s against a 2 s tolerance.
+ *
+ * Deliberately a sibling rather than a refactor of the twin: `parseEtimeToMinutes`
+ * has live callers (`countZombieProcesses`) whose behaviour must not shift.
+ *
+ * Returns null when the format is unrecognised. Pure function.
+ * @param {string} etime
+ * @returns {number|null}
+ */
+export function parseEtimeToSeconds(etime) {
+  if (typeof etime !== 'string') return null;
+  const s = etime.trim();
+  // Same shape as parseEtimeToMinutes: optional "DD-", optional "HH:", then "MM:SS".
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(s);
+  if (!m) return null;
+  const days = parseInt(m[1] ?? '0', 10);
+  const hours = parseInt(m[2] ?? '0', 10);
+  const mins = parseInt(m[3], 10);
+  const secs = parseInt(m[4], 10);
+  if ([days, hours, mins, secs].some(Number.isNaN)) return null;
+  return days * 86400 + hours * 3600 + mins * 60 + secs;
+}
+
 /**
  * Parse the detailed ps output and count Claude/Node zombie candidates.
  * A zombie candidate is a process matching "claude" or "node" that:

package/scripts/lib/resource-probe.mjs

@@ -49,7 +49,7 @@ import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctF
 
 export { evaluate, PROCESSES_PER_SESSION, PRESSURE_HARD_PCT, PRESSURE_SOFT_PCT, PRESSURE_HEALTHY_PCT, DEFAULT_RESOURCE_THRESHOLDS } from './resource-probe/evaluate.mjs';
 export { peerSessionsCount } from './resource-probe/probe-platform.mjs';
-export { parseEtimeToMinutes, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
+export { parseEtimeToMinutes, parseEtimeToSeconds, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
 
 // ---------------------------------------------------------------------------
 // Public API — probe()

package/scripts/lib/rule-loader.mjs

@@ -11,24 +11,26 @@
  * 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'
+ * `paths:` frontmatter convention instead of `globs:` (projects-baseline did
+ * when #795 landed; it now carries both keys — measured count:
+ * docs/baseline.md). 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.
+ * Frontmatter counts ONLY when its opening `---` is the very first line of the
+ * file (#1449) — the same rule Claude Code applies when it reads `paths:`.
+ * Until #1449 this parser skipped leading blank lines and single-line HTML
+ * comments (the vendoring pipeline's `<!-- source: … -->` provenance header),
+ * so a rule Claude Code loads ALWAYS-ON was classified path-scoped here and
+ * `instruction-budget-guard.mjs` under-counted the always-on surface. A
+ * provenance comment now belongs directly AFTER the closing `---` (body text,
+ * inert). A frontmatter-shaped block that is NOT on line 1 — any text,
+ * comment or blank line before it — yields no globs and no meta at all, and
+ * the entry carries `defect: 'frontmatter-not-at-top'` so callers can report
+ * the file instead of silently loading it always-on.
  *
  * Beyond the `globs:` key (issue #336), the frontmatter parser also captures
  * these scalar activation keys (issue #694), surfaced on each RuleEntry:
@@ -149,34 +151,15 @@ function matchGlob(filePath, globPattern) {
 // Minimal YAML frontmatter parser (matches state-md.mjs style)
 // ---------------------------------------------------------------------------
 
+// Anchored at offset 0: frontmatter exists only when `---` is line 1 (#1449).
 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)
+ * Defect code for a frontmatter block that does not start on line 1 (#1449).
+ * Claude Code ignores such a block, so the rule loads always-on there; the
+ * loader mirrors that and tags the entry with this code.
  */
-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');
-}
+export const FRONTMATTER_NOT_AT_TOP = 'frontmatter-not-at-top';
 
 // Scalar activation keys captured (issue #694 + #692). The `globs` key keeps
 // its dedicated sequence/flow handling and is NOT routed through this table.
@@ -192,12 +175,36 @@ const SCALAR_META_KEYS = new Set([
   'tier',
 ]);
 
+/**
+ * Undo the ONE quoting style the renderer emits for a scalar (#1041 follow-up).
+ *
+ * `scripts/lib/reconcile/renderer.mjs` serialises `description:` through
+ * js-yaml, which picks SINGLE-quote style whenever the plain form would be
+ * ambiguous (a `: ` inside) and escapes an interior `'` as `''`. A bare
+ * leading/trailing-quote strip then returns `it''s` for `it's` — measured
+ * 2026-08-23 on 40 of 146 live learning insights carrying both characters.
+ * Single-quoted: strip + un-double. Double-quoted: strip + unescape `\"` and
+ * `\\`. Unquoted: returned verbatim (the pre-#1041 behaviour, unchanged).
+ */
+function unquoteYamlScalar(valuePart) {
+  const v = valuePart.trim();
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    return v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  }
+  return v.replace(/^["']|["']$/g, '');
+}
+
 /**
  * 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
+ *   - `{ globs: 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
  *
  * `globs` is `null` when no frontmatter, and neither `globs:` nor `paths:` is
@@ -212,41 +219,63 @@ const SCALAR_META_KEYS = new Set([
  *   - 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.
+ * Only a block whose opening `---` is line 1 is frontmatter (#1449), exactly
+ * as Claude Code reads it. Anything before the opener — a provenance comment,
+ * a blank line, any text — makes the block body text: no globs, no meta, and
+ * 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> }}
+ * @returns {{ globs: 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, meta: {} };
+}
+
 /**
- * Undo the ONE quoting style the renderer emits for a scalar (#1041 follow-up).
+ * Does `contents` carry a frontmatter block that is NOT on line 1 (#1449)?
  *
- * `scripts/lib/reconcile/renderer.mjs` serialises `description:` through
- * js-yaml, which picks SINGLE-quote style whenever the plain form would be
- * ambiguous (a `: ` inside) and escapes an interior `'` as `''`. A bare
- * leading/trailing-quote strip then returns `it''s` for `it's` — measured
- * 2026-08-23 on 40 of 146 live learning insights carrying both characters.
- * Single-quoted: strip + un-double. Double-quoted: strip + unescape `\"` and
- * `\\`. Unquoted: returned verbatim (the pre-#1041 behaviour, unchanged).
+ * Only the FIRST bare `---` line is considered, and its block must parse
+ * cleanly AND carry at least one key this loader honours (`globs`, `paths`,
+ * or a scalar activation key). That second condition keeps a horizontal rule
+ * pair around ordinary prose from being reported: prose between two `---`
+ * lines almost always holds a colon-less line (a heading, a sentence), which
+ * throws, and a recognised key at column 0 is what makes the misplacement
+ * change behaviour at all. The known blind spot is a displaced block that is
+ * itself malformed — it is treated as body text, which is what Claude Code
+ * does with it too.
+ *
+ * @param {string} contents - raw file contents
+ * @returns {boolean}
  */
-function unquoteYamlScalar(valuePart) {
-  const v = valuePart.trim();
-  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
-    return v.slice(1, -1).replace(/''/g, "'");
-  }
-  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
-    return v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+function hasDisplacedFrontmatter(contents) {
+  const lines = contents.split(/\r?\n/);
+  const opener = lines.indexOf('---');
+  // -1: no opener at all. 0: the opener IS line 1, so FRONTMATTER_RE already
+  // had its chance (an unclosed block) — not a displacement.
+  if (opener <= 0) return false;
+  const block = FRONTMATTER_RE.exec(lines.slice(opener).join('\n'));
+  if (!block) return false;
+  try {
+    const { globs, meta } = parseFrontmatterBlock(block[1]);
+    return globs !== null || Object.keys(meta).length > 0;
+  } catch {
+    return false;
   }
-  return v.replace(/^["']|["']$/g, '');
 }
 
-export function parseGlobsFrontmatter(contents) {
-  const match = FRONTMATTER_RE.exec(stripLeadingProvenanceHeader(contents));
-  if (!match) return { globs: null, meta: {} };
-
-  const fmText = match[1];
+/**
+ * Parses the text BETWEEN the two `---` fences (the frontmatter body).
+ * 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> }}
+ */
+function parseFrontmatterBlock(fmText) {
   const lines = fmText.split(/\r?\n/);
 
   let globsValue = null;
@@ -365,6 +394,35 @@ function metaToEntryFields(meta) {
   return out;
 }
 
+/**
+ * The expiry predicate, shared by the injection gate below and the `/reconcile`
+ * provenance reader (`scripts/lib/reconcile/backlog.mjs`) — one `Date.parse`
+ * for both, so "expired" can never mean two different things to the two
+ * consumers (#1387).
+ *
+ * FAIL-OPEN by design: an absent, empty or unparseable `expires-at` is NOT
+ * expired. Fail-closed here would un-inject (and, in the reconcile reader,
+ * un-materialize) the whole corpus on a single typo.
+ *
+ * Pure apart from the optional `onUnparseable` callback, which exists so the
+ * injection path can keep its stderr WARN while the reconcile reader stays
+ * silent.
+ *
+ * @param {unknown} rawExpiry - the raw `expires-at` frontmatter value (or undefined)
+ * @param {number} [now] - epoch ms; defaults to `Date.now()`
+ * @param {(raw: unknown) => void} [onUnparseable] - called when `expires-at` is present but unparseable
+ * @returns {boolean} true only when a PARSEABLE `expires-at` lies before `now`
+ */
+export function isRuleExpired(rawExpiry, now = Date.now(), onUnparseable) {
+  if (rawExpiry === undefined || rawExpiry === null) return false;
+  const ts = Date.parse(String(rawExpiry));
+  if (Number.isNaN(ts)) {
+    if (typeof onUnparseable === 'function') onUnparseable(rawExpiry);
+    return false;
+  }
+  return ts < now;
+}
+
 /**
  * Deterministic gating check (issue #694 + #692). Returns `{ excluded: boolean,
  * reason?: string }`. Applied to BOTH always-on and glob-matched rules.
@@ -378,18 +436,17 @@ function metaToEntryFields(meta) {
  * @returns {{ excluded: boolean }}
  */
 function applyGates(meta, filePath, mode, hostClass, now, context = null) {
-  // Expiry gate — fail-open on a malformed `expires-at`.
+  // Expiry gate — fail-open on a malformed `expires-at` ({@link isRuleExpired}).
   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`,
-      );
+    if (
+      isRuleExpired(rawExpiry, now, (raw) =>
+        process.stderr.write(
+          `[rule-loader] Rule ${filePath} has unparseable expires-at ${JSON.stringify(raw)} — ignoring expiry\n`,
+        ),
+      )
+    ) {
+      process.stderr.write(`[rule-loader] Rule ${filePath} expired at ${rawExpiry} — excluded\n`);
       return { excluded: true };
     }
   }
@@ -437,6 +494,9 @@ function applyGates(meta, filePath, mode, hostClass, now, context = null) {
  *   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 {'frontmatter-not-at-top'} [defect] - present only when a frontmatter
+ *   block exists but does not start on line 1 (#1449); such an entry is always
+ *   `alwaysOn: true` and carries no meta fields, mirroring Claude Code
  * @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
@@ -455,6 +515,10 @@ function applyGates(meta, filePath, mode, hostClass, now, context = null) {
  * 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.
+ * A rule whose frontmatter does not start on line 1 is always-on with no meta
+ * (so no gate excludes it) and carries `defect: 'frontmatter-not-at-top'`
+ * (#1449) — no stderr line, because callers such as the instruction-budget
+ * guard load the directory several times per run and report the defect themselves.
  *
  * After a successful frontmatter parse, deterministic gates (issue #694) are
  * applied to BOTH always-on and glob-matched rules — a rule must pass ALL
@@ -528,10 +592,11 @@ export function loadApplicableRules({
 
     let globs;
     let meta;
+    let defect;
     let parseError = false;
 
     try {
-      ({ globs, meta } = parseGlobsFrontmatter(content));
+      ({ globs, meta, defect } = parseGlobsFrontmatter(content));
     } catch (err) {
       process.stderr.write(
         `[rule-loader] Frontmatter parse error in ${filePath}: ${err.message} — treating as always-on\n`,
@@ -552,7 +617,8 @@ export function loadApplicableRules({
     const metaFields = metaToEntryFields(meta);
 
     if (globs === null) {
-      // No globs frontmatter (or parse error) → always-on
+      // No globs frontmatter (or parse error, or frontmatter not on line 1 —
+      // #1449) → always-on
       results.push({
         path: filePath,
         content,
@@ -560,6 +626,7 @@ export function loadApplicableRules({
         matchedGlobs: [],
         ...metaFields,
         ...(parseError ? { _parseError: true } : {}),
+        ...(defect ? { defect } : {}),
       });
       continue;
     }