session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/validate/check-validator-registration.mjs

@@ -51,15 +51,21 @@
  * skill body) and nowhere in the three RUN surfaces above still reports
  * UNREGISTERED — being documented is not being run. REVISIT if a fourth run
  * surface (a new CI job file, a different git hook) is ever added: extend
- * `RUN_SURFACES`, do not special-case it here. The comment stripper's own
- * quote-tracking is a single flat state — an escaped quote (`\"`) inside a
- * double-quoted string is not honoured, and a template-literal's `${...}`
- * interpolation is not walked separately. Both failure directions lean
- * toward treating MORE text as "inside a string" than a real parser would,
- * which can only make the stripper MISS a comment (false "still
- * registered"), never manufacture a false UNREGISTERED — the direction this
- * checker's own false-positive history (the paragraph above) already
- * measured as the live hazard.
+ * `RUN_SURFACES`, do not special-case it here.
+ *
+ * THE "NEVER A FALSE UNREGISTERED" CLAIM WAS FALSE (#1388, measured
+ * 2026-09-18 @ 20a4cbff). This header used to argue that the hand-rolled
+ * stripper could only ever MISS a comment, never manufacture a false
+ * UNREGISTERED. It had no regex-literal branch, so
+ * `const re = /\/*$/;` in `scripts/validate-plugin.mjs` opened a BLOCK
+ * COMMENT at the regex's `/*` and swallowed every `runCheck(...)` line below
+ * it — precisely a false UNREGISTERED, for every checker registered after
+ * that point. The `.mjs` surface is therefore lexed by the shared
+ * `maskSource` (`scripts/lib/js-mask.mjs`), which recognises regex literals;
+ * only the `#`-comment shell/YAML surfaces (`.husky/pre-commit`,
+ * `.gitlab-ci.yml`) still use the small local walker, whose flat
+ * quote-tracking ceiling (no `\"` escape handling, no `${...}` walk) is
+ * real but bounded to those two files.
  *
  * Usage: check-validator-registration.mjs <repo-root>
  * Output: `  PASS: …` / `  FAIL: …` lines (two leading spaces), then
@@ -74,6 +80,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
 import { isMainModule } from '../is-main-module.mjs';
+import { maskSource } from '../js-mask.mjs';
 
 /** Marker line inside a checker's own header — declares deliberate CLI-only status. */
 export const STANDALONE_MARKER = /^\s*\/\/\s*registration:\s*standalone\b(?:\s+(.*))?$/m;
@@ -113,11 +120,28 @@ function commentStyleForSurface(rel) {
  * truncating the line early. See the header NAMED CEILING for what this
  * quote-tracking deliberately does not attempt.
  *
+ * The JS style (`//` + `/* *\/`) is delegated to the shared lexer
+ * {@link maskSource} in `keepLiterals` mode — it is the only one of the three
+ * RUN_SURFACES that can contain a REGEX LITERAL, and a stripper without a
+ * regex branch reads `/\/*$/` as a block-comment opener and swallows every
+ * registration below it (#1388, see the header). `maskSource` blanks comment
+ * bytes to SPACES rather than deleting them, which is strictly safer for the
+ * substring match below: deletion could splice two fragments into a basename
+ * that was never written. The `#` style stays local — `maskSource` models
+ * JavaScript, not sh/YAML.
+ *
  * @param {string} text
  * @param {{lineComment: string, blockComment: boolean, quoteChars: string[]}} style
- * @returns {string}
+ * @returns {string} TWO comment models behind one signature, and they differ in
+ * shape: the JS style (`//` + `/* *\/`, delegated to {@link maskSource})
+ * returns a string of the SAME LENGTH as `text`, with comment bytes blanked to
+ * spaces; the `#` style (sh/YAML, the local walker) returns a SHORTER string,
+ * with the comment text deleted to end-of-line (the newline itself is kept).
+ * Only the substring match below is common to both — do not rely on offsets
+ * surviving the `#` style.
  */
 export function stripComments(text, { lineComment, blockComment, quoteChars }) {
+  if (lineComment === '//' && blockComment) return maskSource(text, { keepLiterals: true });
   let out = '';
   let i = 0;
   let inQuote = null;

package/scripts/lib/validate/confidential-names.mjs

@@ -177,6 +177,16 @@ export function inspectConfidentialNames({ namesPath, deps = {} } = {}) {
   // Unconfigured → no list, no noise. This is the normal case for public repos
   // and for any host that has not opted into confidential-name scanning.
   if (typeof namesPath !== 'string' || namesPath.trim() === '') {
+    // UNREACHABLE from the one production caller today (#1273 P1):
+    // `check-owner-leakage.mjs` resolves `namesPath` via `resolveHostPath()`
+    // and returns its own early `disabledReason` on an empty/non-string path
+    // BEFORE ever calling `inspectConfidentialNames` — so in production this
+    // branch never runs. It is reachable only for a direct caller (or a test)
+    // that skips that pre-filter. Kept regardless: `status` is part of the
+    // documented public contract every deep importer may switch on, and
+    // 'unconfigured' is the correct answer for exactly this input shape.
+    // REVISIT TRIGGER (BV-004): the production caller stops pre-filtering an
+    // empty/non-string `namesPath` before calling `inspectConfidentialNames`.
     return { status: 'unconfigured', names: [] };
   }
 

package/scripts/lib/validate-vendored-rules.mjs

@@ -6,17 +6,21 @@
  * Catches vendoring bugs that are invisible at the source-of-truth layer but
  * become live footguns once synced into a target repo:
  *
- *   - `paths:` frontmatter in a `rules/` LIBRARY SOURCE — a vendoring-
- *     CONVENTION gate, not a loader-compatibility one. Since #795
- *     `rule-loader.mjs` accepts `paths:` as an alias for `globs:`, so such a
- *     rule IS glob-scoped; `globs:` stays the canonical form for a rule
- *     vendored out through the library (#742). See § Scope below — this probe
- *     never judges a repo's own consolidated `.claude/rules/` files.
+ *   - `frontmatter-not-at-top` — a `---` block preceded by anything (the
+ *     provenance comment, a blank line). Claude Code reads frontmatter only
+ *     from line 1 and reads only its `paths:` key, so such a rule silently
+ *     loads ALWAYS-ON in every consumer repo (#1449).
+ *   - `globs-paths-mismatch` — a library rule's frontmatter must carry
+ *     `globs:` AND `paths:` with the identical list (order-insensitive), or
+ *     neither. `paths:` is what Claude Code reads; `globs:` stays because
+ *     `rule-loader.mjs` prefers it (#742/#795). One key alone, or two
+ *     different lists, scopes the rule differently per loader.
  *   - Missing provenance header — `rules-sync.mjs` detects "plugin-owned vs.
- *     local override" purely by checking whether the first line starts with
- *     `PLUGIN_HEADER_PREFIX`. A source file missing that header gets
- *     mis-detected as a local override on the NEXT re-sync (it looks
- *     hand-authored), so the plugin can never update it again.
+ *     local override" via `isPluginOwnedContent()`: the header line starting
+ *     with `PLUGIN_HEADER_PREFIX` on line 1 (a rule without frontmatter) or as
+ *     the first non-blank line after a line-1 frontmatter block. A source file
+ *     missing it gets mis-detected as a local override on the NEXT re-sync (it
+ *     looks hand-authored), so the plugin can never update it again.
  *   - Unfilled placeholder tokens (`{{PROJECT_NAME}}`-style, `## TODO:
  *     Customize` headings, `<!-- TODO:` comments) leaking from an
  *     un-filled-in skeleton into a synced rule.
@@ -30,9 +34,10 @@
  * Stdlib-only ESM, with the same picomatch-with-fallback resolution pattern
  * as `rule-loader.mjs` (duplicated here rather than imported because those
  * helpers are module-private there — the *approach* is reused, not
- * reinvented). Frontmatter `globs:` extraction is NOT duplicated — this
- * module imports the already-exported `parseGlobsFrontmatter` from
- * `rule-loader.mjs` directly.
+ * reinvented). The globs-derived probes use the already-exported
+ * `parseGlobsFrontmatter` from `rule-loader.mjs` directly; only
+ * `globs-paths-mismatch` reads the two keys itself (`readScopeKeys`), because
+ * the loader merges them and cannot say which key carried which list.
  *
  * ## Scope: the `rules/` fleet library, never a repo's own `.claude/rules/`
  *
@@ -43,15 +48,14 @@
  * written target is never read back through the gate. The CLI's `--dir` is
  * operator-supplied and means that same library.
  *
- * This is load-bearing for `paths-frontmatter`: a repo's own CONSOLIDATED rules
- * under `.claude/rules/` are `paths:`-canonical by design, because Claude
- * Code's native loader reads ONLY `paths:` and treats a rule without it as
- * always-on (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md`
- * § Consolidated rules point 3). Measured 2026-09-16 in this repo: 10
- * path-scoped rule files there, 9 of them `paths:`-only. Pointing `--dir` at
- * such a tree would emit findings that, if obeyed, UNDO that consolidation —
- * which is also why `check-rules.mjs` deliberately does not duplicate this
- * probe for `.claude/rules/`.
+ * This matters for `globs-paths-mismatch` and the provenance probe: they encode
+ * the LIBRARY convention (both scope keys, a provenance header). A repo's own
+ * CONSOLIDATED rules under `.claude/rules/` are `paths:`-only and header-free
+ * by design, because Claude Code's native loader reads ONLY `paths:`
+ * (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md` § Consolidated
+ * rules point 3). Measured 2026-09-16 in this repo: 10 path-scoped rule files
+ * there, 9 of them `paths:`-only. Pointing `--dir` at such a tree reports
+ * findings about a convention those files were never meant to follow.
  *
  * @module validate-vendored-rules
  */
@@ -61,7 +65,7 @@ import { join, resolve, relative, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { parseGlobsFrontmatter } from './rule-loader.mjs';
+import { parseGlobsFrontmatter, FRONTMATTER_NOT_AT_TOP } from './rule-loader.mjs';
 import { isMainModule } from './is-main-module.mjs';
 
 // Mirrors rules-sync.mjs's exported PLUGIN_HEADER_PREFIX (rules-sync.mjs
@@ -137,21 +141,26 @@ function matchGlob(filePath, globPattern) {
 // Frontmatter helpers
 // ---------------------------------------------------------------------------
 
+// A line that may precede a MISPLACED frontmatter opener: blank, or one
+// complete single-line HTML comment (the provenance header's shape).
 const HEADER_LINE_RE = /^[ \t]*(?:<!--.*-->)?[ \t]*$/;
 
 /**
- * Finds a YAML frontmatter block delimited by `---` lines.
+ * Locates a YAML frontmatter block delimited by `---` lines.
  *
- * Mirrors rule-loader.mjs's header-tolerant frontmatter shape for the `paths:`
- * authoring guard: a leading run of blank lines and/or single-line HTML
- * comments may precede the opening `---`.
+ * Deliberately tolerant of a leading run of blank lines and/or single-line
+ * HTML comments before the opener — NOT because such a block is valid (Claude
+ * Code reads frontmatter only when `---` is line 1, and `rule-loader.mjs`
+ * no longer tolerates the prefix either), but so `frontmatter-not-at-top` can
+ * SEE the misplaced block and report it. Callers that judge what a loader
+ * reads must check `startLine === 0` first.
  *
- * @param {string} content
- * @returns {{ body: string, startLine: number } | null} startLine is the
- *   0-based file-line index of the opening `---`.
+ * @param {string[]} lines - file content split on `\r?\n`
+ * @returns {{ bodyLines: string[], startLine: number, endLine: number } | null}
+ *   startLine / endLine are the 0-based file-line indices of the opening and
+ *   closing `---`.
  */
-function extractFrontmatter(content) {
-  const lines = content.split(/\r?\n/);
+function locateFrontmatter(lines) {
   let startLine = 0;
   while (startLine < lines.length && HEADER_LINE_RE.test(lines[startLine])) {
     startLine++;
@@ -159,22 +168,93 @@ function extractFrontmatter(content) {
   if (lines[startLine] !== '---') return null;
   for (let i = startLine + 1; i < lines.length; i++) {
     if (lines[i] === '---') {
-      return { body: lines.slice(startLine + 1, i).join('\n'), startLine };
+      return { bodyLines: lines.slice(startLine + 1, i), startLine, endLine: i };
     }
   }
   return null;
 }
 
 /**
- * Line number (1-based, absolute within the file) of a match at `bodyIndex`
- * inside the frontmatter body.
- * @param {number} startLine - 0-based file-line index of the opening `---`
- * @param {string} body - frontmatter body text
- * @param {number} bodyIndex - character offset within body
- * @returns {number}
+ * True when `content` carries the plugin provenance header in one of the two
+ * positions the vendoring convention allows (#1449):
+ *
+ *   (a) line 1 — a rule WITHOUT frontmatter, and also every vendored copy
+ *       written before #1449 (header on line 1, frontmatter after it);
+ *   (b) the first non-blank line after the closing `---` of a frontmatter
+ *       block that opens on line 1 — the current format for a rule WITH
+ *       frontmatter, because Claude Code reads `paths:` only from a line-1
+ *       block.
+ *
+ * This is the ownership predicate `rules-sync.mjs` uses to tell a
+ * plugin-owned vendored copy (rewrite it) from a local rule (preserve it), and
+ * the `provenance-header` probe's acceptance test. Accepting (a) with a
+ * frontmatter after it keeps old-format consumer copies plugin-owned, so the
+ * next sync REWRITES them into the new format instead of preserving them
+ * forever. Lives here rather than in rules-sync.mjs because rules-sync.mjs
+ * imports from this module; it re-exports this function.
+ *
+ * @param {string} content - raw rule file content
+ * @returns {boolean}
  */
-function lineWithinFrontmatter(startLine, body, bodyIndex) {
-  return startLine + 1 + body.slice(0, bodyIndex).split('\n').length;
+export function isPluginOwnedContent(content) {
+  const lines = content.split(/\r?\n/);
+  if ((lines[0] ?? '').startsWith(PLUGIN_HEADER_PREFIX)) return true;
+  const fm = locateFrontmatter(lines);
+  if (!fm || fm.startLine !== 0) return false;
+  const next = lines.slice(fm.endLine + 1).find((l) => l.trim() !== '');
+  return next !== undefined && next.startsWith(PLUGIN_HEADER_PREFIX);
+}
+
+/**
+ * Strips one pair of surrounding quotes, as rule-loader.mjs does for list items.
+ * @param {string} s
+ * @returns {string}
+ */
+function unquoteItem(s) {
+  return s.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Reads the `globs:` and `paths:` sequences of a frontmatter body EACH ON ITS
+ * OWN. `parseGlobsFrontmatter()` cannot answer this: it merges the two keys by
+ * design (`globs:` wins, `paths:` is discarded), so it cannot say which key
+ * carried which list. Accepts the three value shapes rule-loader.mjs accepts —
+ * indented block list, flow list `[a, b]`, single inline value.
+ *
+ * @param {string[]} bodyLines - frontmatter lines between the `---` markers
+ * @returns {{ globs?: { values: string[], index: number }, paths?: { values: string[], index: number } }}
+ *   `index` is the 0-based body line of the key.
+ */
+function readScopeKeys(bodyLines) {
+  /** @type {{ globs?: { values: string[], index: number }, paths?: { values: string[], index: number } }} */
+  const found = {};
+  let active = null;
+  bodyLines.forEach((raw, index) => {
+    const line = raw.replace(/\s+$/, '');
+    if (line === '' || /^\s*#/.test(line)) return;
+    if (active) {
+      const item = /^\s+-\s+(.*)$/.exec(line);
+      if (item) {
+        found[active].values.push(unquoteItem(item[1]));
+        return;
+      }
+      active = null;
+    }
+    const key = /^(globs|paths):\s*(.*)$/.exec(line);
+    if (!key) return;
+    const [, name, value] = key;
+    let values = [];
+    if (value === '') {
+      active = name;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      values = inner === '' ? [] : inner.split(',').map(unquoteItem);
+    } else {
+      values = [unquoteItem(value)];
+    }
+    found[name] = { values, index };
+  });
+  return found;
 }
 
 /**
@@ -463,7 +543,7 @@ const FOREIGN_TOKEN_RE = /[A-Z][a-z]+[A-Z]/;
 
 /**
  * @typedef {object} RuleViolation
- * @property {string} rule - check id (paths-frontmatter | provenance-header | placeholder | zero-match-globs | foreign-glob)
+ * @property {string} rule - check id (frontmatter-not-at-top | globs-paths-mismatch | provenance-header | placeholder | zero-match-globs | foreign-glob)
  * @property {'error'|'warn'} severity
  * @property {string} message
  * @property {number} [line] - 1-based line number, when known
@@ -486,52 +566,94 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
   /** @type {RuleViolation[]} */
   const violations = [];
 
-  // ---- paths-frontmatter (error) ----
-  const fm = extractFrontmatter(content);
-  if (fm) {
-    const pathsMatch = /^paths:/m.exec(fm.body);
-    if (pathsMatch) {
+  const lines = content.split(/\r?\n/);
+  const fm = locateFrontmatter(lines);
+
+  // ---- frontmatter-not-at-top (error) ----
+  // Claude Code reads frontmatter only when `---` is line 1. Anything before
+  // it (the provenance comment, a blank line) makes it see NO frontmatter, so
+  // a path-scoped rule loads ALWAYS-ON in every consumer repo, with no error.
+  // Two detectors, one verdict (BV-003): `locateFrontmatter` sees a block
+  // behind blank lines / single-line comments (the provenance shape);
+  // `parseGlobsFrontmatter` (the loader — the same code the wave injector
+  // runs) additionally sees one behind ANY text, e.g. a heading. Either
+  // signal is the defect; the finding is reported once.
+  const loaderDefect = parseGlobsFrontmatter(content).defect === FRONTMATTER_NOT_AT_TOP;
+  if ((fm && fm.startLine !== 0) || (!(fm && fm.startLine === 0) && loaderDefect)) {
+    const openerLine = fm ? fm.startLine + 1 : lines.findIndex((l) => l === '---') + 1;
+    violations.push({
+      rule: 'frontmatter-not-at-top',
+      severity: 'error',
+      message:
+        `${relPath}: the frontmatter block opens on line ${openerLine}, not line 1. ` +
+        `Claude Code reads frontmatter only when '---' is the very first line, so it sees none ` +
+        `here and loads this rule always-on, ignoring its 'paths:' scope. Move the block to the ` +
+        `top; the provenance header goes on the first line after the closing '---'.`,
+      line: 1,
+    });
+  }
+
+  // ---- globs-paths-mismatch (error) ----
+  // Judged only on a line-1 block: a misplaced block is read by no loader,
+  // and frontmatter-not-at-top already reports it.
+  if (fm && fm.startLine === 0) {
+    const { globs, paths } = readScopeKeys(fm.bodyLines);
+    // body index i sits on 1-based file line i + 2 when the opener is line 1.
+    const keyLine = (k) => k.index + 2;
+    let detail = null;
+    let line;
+    if (globs && !paths) {
+      detail =
+        `declares 'globs:' but no 'paths:'. Claude Code reads only 'paths:', so it loads this ` +
+        `rule always-on. Add 'paths:' carrying the identical list.`;
+      line = keyLine(globs);
+    } else if (paths && !globs) {
+      detail =
+        `declares 'paths:' but no 'globs:'. rule-loader.mjs prefers 'globs:' (#742/#795); a ` +
+        `rule vendored out through the plugin's rules/ library carries both keys. Add 'globs:' ` +
+        `carrying the identical list. This does NOT apply to a repo's own consolidated ` +
+        `.claude/rules/ files — those are paths:-only by design and this gate never scans them.`;
+      line = keyLine(paths);
+    } else if (globs && paths) {
+      const g = new Set(globs.values);
+      const p = new Set(paths.values);
+      const onlyGlobs = [...g].filter((x) => !p.has(x));
+      const onlyPaths = [...p].filter((x) => !g.has(x));
+      if (onlyGlobs.length > 0 || onlyPaths.length > 0) {
+        detail =
+          `'globs:' and 'paths:' carry different lists (only in globs: ${JSON.stringify(onlyGlobs)}; ` +
+          `only in paths: ${JSON.stringify(onlyPaths)}). Claude Code scopes by 'paths:', ` +
+          `rule-loader.mjs by 'globs:', so the two would activate this rule on different files. ` +
+          `Make both lists identical.`;
+        line = keyLine(globs.index <= paths.index ? globs : paths);
+      }
+    }
+    if (detail) {
       violations.push({
-        rule: 'paths-frontmatter',
+        rule: 'globs-paths-mismatch',
         severity: 'error',
-        // NOTE (#795 / corrected 2026-07-25): the previous wording claimed rule-loader.mjs
-        // does not recognize `paths:` and that such a rule loads always-on. Both are false
-        // since #795 — `rule-loader.mjs:275` accepts `paths` alongside `globs`, and `:313`
-        // treats it as a fallback alias (`globs:` wins silently when both are present), so a
-        // `paths:`-only rule IS glob-scoped. The probe itself stays: it enforces the canonical
-        // vendoring form, which is a convention gate, not a loader-compatibility gate. That
-        // intent survives #795 and is the subject of the #742 fleet canonicalisation sweep.
-        // SCOPE (2026-09-16): this fires only over `rules/` library sources — the module doc's
-        // § Scope section names every caller. Do NOT re-point it at a repo's own
-        // `.claude/rules/`: those consolidated files are `paths:`-canonical and obeying this
-        // remedy there would undo the consolidation (docs/rule-authoring.md point 3).
-        message:
-          `${relPath}: frontmatter declares a top-level 'paths:' key. It is a recognized alias ` +
-          `for 'globs:' (issue #795), so the rule does load glob-scoped — but 'globs:' is the ` +
-          `canonical form for a rule VENDORED OUT through the plugin's rules/ library, which is ` +
-          `this probe's only population. Migrate to 'globs:' (see issue #742). This does NOT ` +
-          `apply to a repo's own consolidated .claude/rules/ files — those are paths:-canonical ` +
-          `(Claude Code's native loader reads only 'paths:') and this gate never scans them.`,
-        line: lineWithinFrontmatter(fm.startLine, fm.body, pathsMatch.index),
+        message: `${relPath}: frontmatter ${detail}`,
+        line,
       });
     }
   }
 
   // ---- provenance-header (error, opt-in) ----
-  if (requireProvenance) {
-    const firstLine = content.split('\n')[0] ?? '';
-    if (!firstLine.startsWith(PLUGIN_HEADER_PREFIX)) {
-      violations.push({
-        rule: 'provenance-header',
-        severity: 'error',
-        message:
-          `${relPath}: missing provenance header — the first line must start with ` +
-          `${JSON.stringify(PLUGIN_HEADER_PREFIX)} (see rules-sync.mjs PLUGIN_HEADER_PREFIX). ` +
-          `Without it, rules-sync.mjs mis-detects this file as a local override on the next re-sync ` +
-          `and will never update it again.`,
-        line: 1,
-      });
-    }
+  // A header on line 1 followed by a frontmatter is accepted HERE (the file
+  // has a header, and isPluginOwnedContent must keep old vendored copies
+  // plugin-owned); frontmatter-not-at-top reports that shape, once.
+  if (requireProvenance && !isPluginOwnedContent(content)) {
+    violations.push({
+      rule: 'provenance-header',
+      severity: 'error',
+      message:
+        `${relPath}: missing provenance header — a line starting with ` +
+        `${JSON.stringify(PLUGIN_HEADER_PREFIX)} (see rules-sync.mjs PLUGIN_HEADER_PREFIX) must ` +
+        `stand either on line 1 (a rule without frontmatter) or on the first non-blank line after ` +
+        `the closing '---' of a frontmatter that opens on line 1. Without it, rules-sync.mjs ` +
+        `mis-detects this file as a local override on the next re-sync and will never update it again.`,
+      line: 1,
+    });
   }
 
   // ---- placeholder (error) — skip matches inside fenced code blocks ----
@@ -569,6 +691,9 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
   }
 
   // ---- globs: derived checks (zero-match-globs, foreign-glob) ----
+  // Driven by the loader's own parse, so these judge exactly the list
+  // rule-loader.mjs will scope by (`globs:`, else its `paths:` alias). On a
+  // misplaced block that yields no globs — frontmatter-not-at-top covers it.
   let globs;
   try {
     ({ globs } = parseGlobsFrontmatter(content));
@@ -617,8 +742,9 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
 }
 
 /**
- * Validates every `*.md` rule file under `dir`, recursively (skips dotfiles
- * and `_index.md`).
+ * Validates every `*.md` rule file under `dir`, recursively (skips dotfiles,
+ * `_index.md` and `README.md` — neither is a vendored rule: `rules-sync.mjs`
+ * vendors only the entries listed in `_index.md`, #1164).
  *
  * When `pluginRoot` is given, every scanned file is additionally passed through
  * `scanVendoringLeaks()` and the findings are collected into the additive
@@ -642,7 +768,7 @@ export function validateRulesDir({ dir, targetRoot = null, requireProvenance = f
       const absPath = join(absDir, entry.name);
       if (entry.isDirectory()) {
         files.push(...collectRuleFiles(absPath));
-      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_index.md') {
+      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_index.md' && entry.name !== 'README.md') {
         files.push(relative(dir, absPath).replace(/\\/g, '/'));
       }
     }

package/scripts/lib/vault-mirror/namespace.mjs

@@ -5,10 +5,18 @@
  * vault writes under `40-learnings/<repoNs>/` and `50-sessions/<repoNs>/`.
  *
  * Contract:
- *   resolveRepoNamespace({ vaultName?, cwd? }) → string
+ *   resolveRepoNamespace({ vaultName?, repoRoot? }) → string
  *
- *   - Pure + deterministic (given the same git remote / cwd / vaultName input,
- *     and the same host-local pseudonym map).
+ *   - Pure + deterministic (given the same vaultName, the same `.vault.yaml`
+ *     under `repoRoot`, the same git remote, and the same host-local pseudonym
+ *     map).
+ *   - `repoRoot` (#1389) selects the directory whose `.vault.yaml` is read;
+ *     it defaults to `process.cwd()`. Named limit: it scopes ONLY that lookup —
+ *     the {@link deriveRepo} fallback still resolves from the process cwd and
+ *     is cached per process, so a `repoRoot` that differs from the cwd AND has
+ *     no declared slug falls back to the cwd's git identity. Every production
+ *     caller passes its own cwd today; revisit if a caller ever mirrors a repo
+ *     other than the one it runs in.
  *   - Returns a lowercase kebab slug safe for use as a filesystem path segment.
  *   - Host-local pseudonym mapping (Epic #725 D5): consulted ONLY at the redaction
  *     site (only when a segment is owner-leaky). If such a repo (raw or sanitised)
@@ -47,6 +55,7 @@ import { isOwnerLeakySegment } from '../../lib/validate/check-owner-leakage.mjs'
 import { loadPseudonymMap } from './pseudonym-map.mjs';
 import { loadHostPaths, resolveHostPath } from '../config/host-paths.mjs';
 import { isQueryFailure, resolvePreferredRemote } from '../vcs-repo-spec.mjs';
+import { readVaultSlug } from '../vault-yaml.mjs';
 
 // ── Lazy pseudonym-map path resolution (Epic #725 D5) ────────────────────────
 // The map path comes from env SO_NAMESPACE_MAP > owner.yaml paths.namespace-map-path
@@ -237,19 +246,48 @@ function lookupPseudonym(base, seg) {
  *
  * @param {object}  [opts]
  * @param {string|null} [opts.vaultName] - Optional override for the repo identifier.
- *   When non-empty and non-whitespace, used in place of the git-derived repo name.
- *   When absent, the namespace is derived from the git origin via deriveRepo().
+ *   When non-empty and non-whitespace, used in place of the declared/git-derived
+ *   repo name. When absent, the base is the repo's declared `.vault.yaml`
+ *   `metadata.slug` (#1131), else the git origin via deriveRepo().
+ * @param {string|null} [opts.repoRoot] - Directory whose `.vault.yaml` supplies
+ *   the declared slug (#1389). `undefined`/`null` → `process.cwd()`. Does NOT
+ *   redirect the deriveRepo() fallback (see the module header's named limit).
  * @returns {string} A single kebab-slug path segment, e.g. 'session-orchestrator'.
  *   Special returns:
  *   - 'unknown-repo'  — slug derivation produced an empty string.
  *   - 'redacted-repo' — the raw or slugified value matched an owner-leakage pattern
  *     (CP1 personal home path / CP6 private slug / CP10 personal name in Projects path).
  */
-export function resolveRepoNamespace({ vaultName = null } = {}) {
-  // Choose the base identifier: explicit override first, then git-derived.
+export function resolveRepoNamespace({ vaultName = null, repoRoot = null } = {}) {
+  // Choose the base identifier. Precedence: explicit `vaultName` override >
+  // the repo's declared `.vault.yaml` `metadata.slug` (#1131) > git-derived.
+  //
+  // WHY the slug sits HERE and not in deriveRepo(): deriveRepo() is the RAW
+  // repo IDENTITY (`org/repo`) and has consumers that want exactly that and
+  // nothing else — `vault-relocation-rules.mjs`, `relocate-vault-corpus.mjs`,
+  // `named-vault-resolver.mjs` (which documents the `org/repo-name` format).
+  // #1131 concerns the vault FOLDER namespace, which is what THIS function
+  // decides, so the lookup belongs at this candidate-selection point.
+  //
+  // Note what this placement does NOT buy: the `source-repo:` frontmatter is
+  // this function's output, not deriveRepo()'s (#732; process.mjs deliberately
+  // shares ONE value between the write path and the rendered field), so a repo
+  // whose declared slug differs from its derived name gets a new `source-repo`
+  // either way. That is inherent to moving the folder, not a side effect of
+  // where the lookup lives.
+  //
+  // It sits BELOW `vaultName` (an explicit per-call/operator override must stay
+  // honourable) and ABOVE derivation (a declared registration beats a guess from
+  // the remote URL or the checkout directory: the remote answers "where does
+  // this code live?", the slug answers "which vault project IS this?", and a
+  // host-side rename legitimately diverges the two). It sits ABOVE the leak
+  // guard below deliberately — a declared slug is operator data flowing into a
+  // written path and is checked by CP1/CP6/CP10 and the pseudonym map exactly
+  // like any git-derived identifier.
+  const declaredSlug = readVaultSlug(repoRoot ?? process.cwd());
   const base = (vaultName && typeof vaultName === 'string' && vaultName.trim())
     ? vaultName.trim()
-    : deriveRepo();
+    : (declaredSlug ?? deriveRepo());
 
   // Sanitise: collapse to last path segment, lowercase, strip non-[a-z0-9-].
   const seg = subjectToSlug(base);

package/scripts/lib/vault-mirror/process.mjs

@@ -666,8 +666,12 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     });
   }
 
-  // #660: namespace new writes under a per-repo subdirectory.
-  const repoNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null });
+  // #660: namespace new writes under a per-repo subdirectory. #1389: `ctx.repoRoot`
+  // is optional — absent, resolveRepoNamespace falls back to process.cwd().
+  const repoNs = resolveRepoNamespace({
+    vaultName: ctx?.vaultName ?? null,
+    repoRoot: ctx?.repoRoot ?? null,
+  });
   // #725 D2: thread the resolved repo namespace into the learning frontmatter as
   // `source-repo` for cross-repo attribution. repoNs is already sanitised +
   // leak-guarded by resolveRepoNamespace, so it is safe to interpolate as-is. The
@@ -898,7 +902,10 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // owner-leaky repo's real name reached the vault through the session-note
   // frontmatter even though the directory AND the learning `source-repo` field
   // were already pseudonym-mapped/redacted (#732 leak-guard bypass).
-  const repoNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null });
+  const repoNs = resolveRepoNamespace({
+    vaultName: ctx?.vaultName ?? null,
+    repoRoot: ctx?.repoRoot ?? null,
+  });
 
   // Quality gate (PRD F1.2): skip sessions whose rendered narrative is too short.
   // Measure on the rendered markdown body so the check is schema-agnostic across

package/scripts/lib/vault-mirror/render-sessions.mjs

@@ -476,14 +476,24 @@ export function generateSessionNote(entry, options = {}) {
       // #1276: lifecycle-only records omit every older count alias. Started
       // measures participation; completed/planned-only counts retain their
       // labels so a plan or a completion count never claims dispatch coverage.
-      const completedAgents = waveCount(w.agent_count_completed);
-      const plannedAgents = waveCount(w.agent_count_planned);
+      // The `agents_*` triple is the same lifecycle measurement under the
+      // de-underscored producer spelling: `metrics-collection.md` documents
+      // `agent_count_{planned,started,completed}`, but the live ledger carries
+      // one session (`main-2026-09-18-session-1`, 5 waves, measured 2026-09-18
+      // over `.orchestrator/metrics/sessions.jsonl`) whose waves emit only
+      // `agents_planned` / `agents_started` / `agents_completed` — every one of
+      // its 15 counts rendered `?` beside a real number, exactly the #1074 bug
+      // class. Each alias sits at the precedence of its documented twin, so no
+      // cell that already rendered a value can change.
+      const completedAgents = waveCount(w.agent_count_completed) ?? waveCount(w.agents_completed);
+      const plannedAgents = waveCount(w.agent_count_planned) ?? waveCount(w.agents_planned);
       const agentsCell =
         waveCount(w.agent_count) ??
         waveCount(w.agents) ??
         waveCount(w.agents_dispatched) ??
         waveCount(w.dispatched) ??
         waveCount(w.agent_count_started) ??
+        waveCount(w.agents_started) ??
         (completedAgents === undefined ? undefined : `${completedAgents} completed`) ??
         (plannedAgents === undefined ? MISSING_CELL : `${plannedAgents} planned`);
       const filesCell = waveCount(w.files_changed) ?? waveCount(w.files) ?? MISSING_CELL;