session-orchestrator 5.3.0 → 5.4.0

package/scripts/lib/rule-loader.mjs

@@ -20,16 +20,17 @@
  * `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:
@@ -150,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.
@@ -193,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
@@ -213,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;
@@ -466,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
@@ -484,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
@@ -557,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`,
@@ -581,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,
@@ -589,6 +626,7 @@ export function loadApplicableRules({
         matchedGlobs: [],
         ...metaFields,
         ...(parseError ? { _parseError: true } : {}),
+        ...(defect ? { defect } : {}),
       });
       continue;
     }

package/scripts/lib/rules-sync.mjs

@@ -3,26 +3,37 @@
  * Syncs canonical rules from the plugin's rules/ library into a consumer repo's .claude/rules/.
  *
  * Stdlib-only, cross-platform, no Zod, no third-party parsers. ESM module.
- * Preserves local rules (files without the plugin source header).
+ * Preserves local rules — files carrying the plugin provenance header in
+ * neither accepted position (see `isPluginOwnedContent`).
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { validateRuleContent, scanVendoringLeaks } from './validate-vendored-rules.mjs';
+import {
+  validateRuleContent,
+  scanVendoringLeaks,
+  isPluginOwnedContent,
+} from './validate-vendored-rules.mjs';
 import { isMainModule } from './is-main-module.mjs';
 
 // The vendoring sanitizer (issue #1098) lives in validate-vendored-rules.mjs —
 // it has that module's shape ("judge one rule file → findings") and its
 // standalone CLI needs it too. Re-exported here so importers that predate the
 // move (and this file's own tests) keep resolving it from rules-sync.mjs.
-export { scanVendoringLeaks };
+//
+// isPluginOwnedContent (#1449) — the ownership predicate below — lives there
+// for the same reason as PLUGIN_HEADER_PREFIX's copy: this module imports
+// validate-vendored-rules.mjs, so defining it here and importing it back into
+// the validator's provenance probe would make the two modules import each
+// other. Re-exported so the ownership rule is reachable from the sync module.
+export { scanVendoringLeaks, isPluginOwnedContent };
 
 // Exported (issue #722 Epic A Wave 2) for external consumers (e.g. tests).
-// NOT imported by validate-vendored-rules.mjs — that module imports
-// validateRuleContent FROM this file (see the pre-write gate below), so
-// importing this constant back would create a module-load cycle; it keeps
-// its own textually-identical copy instead.
+// NOT imported by validate-vendored-rules.mjs — this module imports
+// validateRuleContent FROM that file (see the pre-write gate below), so
+// importing this constant back there would create a module-load cycle; it
+// keeps its own textually-identical copy instead.
 export const PLUGIN_HEADER_PREFIX = '<!-- source: session-orchestrator plugin';
 
 /**
@@ -170,8 +181,9 @@ function escapeRegex(s) {
  *
  * When `validate` is true (the default — issue #722 Epic A Wave 2),
  * validateRuleContent() runs as a pre-write gate on every source file before
- * it is copied. A file with any error-severity violation (paths-frontmatter,
- * missing provenance header, unfilled placeholder) is recorded in `errors[]`
+ * it is copied. A file with any error-severity violation (frontmatter-not-at-top,
+ * globs-paths-mismatch, missing provenance header, unfilled placeholder) is
+ * recorded in `errors[]`
  * and its write is skipped entirely — it is never added to
  * written/skipped/preserved. Warn-severity violations (zero-match-globs,
  * foreign-glob) do NOT block the write; they are collected into the
@@ -405,9 +417,12 @@ export function syncRules({
         continue;
       }
 
-      const firstLine = targetContent.split('\n')[0] ?? '';
-      if (!firstLine.startsWith(PLUGIN_HEADER_PREFIX)) {
-        // Local file — preserve it
+      // Ownership accepts BOTH header positions (#1449): line 1 (the format
+      // every copy vendored before #1449 carries, frontmatter or not) and the
+      // first non-blank line after a line-1 frontmatter (the current format).
+      // So an old-format copy is rewritten into the new format below, never
+      // preserved; only a file with no header in either position is local.
+      if (!isPluginOwnedContent(targetContent)) {
         preserved.push(fileName);
         continue;
       }

package/scripts/lib/scope-baseline.mjs

@@ -604,10 +604,9 @@ export function computeDrift({ repoRoot, threshold = 2.0 } = {}) {
     ? plannedFilesRaw
     : 0;
 
-  // Mirrors the existing over_delivery_ratio div-by-zero guard in
-  // skills/wave-executor/wave-loop.md (`files_changed / max(planned_files_count, 1)`,
-  // in the per-wave metrics section). Deliberately un-line-pinned: that file is
-  // edited often enough that a pinned number goes stale, as this very comment did.
+  // Division-by-zero guard: a baseline that froze zero planned files (no declared
+  // file scope, or a non-numeric count coerced to 0 above) would otherwise yield
+  // Infinity or NaN; `max(plannedFiles, 1)` keeps the ratio finite and comparable.
   const filesRatio = round2(actualFiles / Math.max(plannedFiles, 1));
   const breached = filesRatio >= threshold;