session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/config/config-protection.mjs

@@ -1,4 +1,5 @@
 import { matchBlockHeader } from './block-header.mjs';
+import { isSessionConfigHeading } from './section-extractor.mjs';
 
 /**
  * config-protection.mjs — Parser for the top-level `config-protection:` YAML
@@ -109,7 +110,7 @@ export function _isConfigWeakeningAllowed(content) {
   const lines = content.split(/\r?\n/);
   let inConfig = false;
   for (const line of lines) {
-    if (line === '## Session Config') { inConfig = true; continue; }
+    if (isSessionConfigHeading(line)) { inConfig = true; continue; }
     if (inConfig && /^## /.test(line)) break;
     if (inConfig) {
       const m = line.match(/^\s*(?:-\s+\*\*)?allow-config-weakening(?::\*\*)?\s*:\s*(\S+)/);

package/scripts/lib/config/context-coverage.mjs

@@ -0,0 +1,82 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * context-coverage.mjs — Parser for the top-level `context-coverage:` YAML block.
+ *
+ * Config block shape (see docs/session-config-template.md):
+ *   context-coverage:
+ *     enabled: false
+ *     mode: warn
+ *
+ * Modelled on `./docs-staleness.mjs`'s parser design (issue #781, Epic #774) —
+ * the block is scoped from the raw file content, independent of the
+ * `## Session Config` section boundary, so a baseline using either the plain
+ * `key:` header or the bold-bullet markdown rendering
+ * (`- **context-coverage:**`, tolerated via `matchBlockHeader()`) parses
+ * identically.
+ *
+ * ZERO imports other than `./block-header.mjs` — `tests/lib/config/cycle-guard.test.mjs`
+ * forbids importing `../config.mjs` from this directory; this module keeps a
+ * clean leaf with no other dependencies at all.
+ *
+ * Not registered in `scripts/lib/config.mjs` here — the coordinator wires
+ * `_parseContextCoverage` into the orchestrator's config-object assembly
+ * separately (see `context-coverage-banner.mjs`'s header for the exact
+ * import + call lines to add there).
+ *
+ * Shipped default: `{ enabled: false, mode: 'warn' }` — opt-in (issue #831).
+ */
+
+/**
+ * Parse the top-level `context-coverage:` YAML block from markdown content.
+ * Defaults: enabled=false, mode="warn". Malformed values fall back per key.
+ *
+ * @param {string} content — full file contents
+ * @returns {{enabled: boolean, mode: string}}
+ */
+export function _parseContextCoverage(content) {
+  const defaults = { enabled: false, mode: 'warn' };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'context-coverage')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let ccEnabled = false;
+  let ccMode = 'warn';
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        ccEnabled = v.toLowerCase() === 'true';
+        break;
+      case 'mode':
+        if (['strict', 'warn', 'off'].includes(v)) ccMode = v;
+        break;
+    }
+  }
+
+  return { enabled: ccEnabled, mode: ccMode };
+}

package/scripts/lib/config/drift-check.mjs

@@ -99,7 +99,15 @@ export function _parseDriftCheck(content) {
         dcEnabled = v.toLowerCase() === 'true';
         break;
       case 'mode':
-        if (['hard', 'warn', 'off'].includes(v)) dcMode = v;
+        // Enum: strict|warn|off. `hard` is a legacy alias for `strict`,
+        // normalized here. This is the drift-check half of the #217 enum
+        // migration (vault-sync moved hard→strict on 2026-04-21; drift-check
+        // was forgotten, so a committed `mode: strict` silently fell back to
+        // the `warn` default and the narrative-drift gate ran unenforced).
+        // Invalid values still fall back to the 'warn' default below.
+        if (['strict', 'hard', 'warn', 'off'].includes(v)) {
+          dcMode = v === 'hard' ? 'strict' : v;
+        }
         break;
       case 'include-paths':
         if (!v) inIncludeList = true;

package/scripts/lib/config/gitlab-portfolio.mjs

@@ -9,7 +9,7 @@ export const GITLAB_PORTFOLIO_DEFAULTS = {
   enabled: false,
   mode: 'warn',
   'stale-days': 30,
-  'critical-labels': ['priority:critical', 'priority:high'],
+  'critical-labels': ['priority::critical', 'priority::high'],
 };
 
 const VALID_MODES = new Set(['warn', 'strict', 'off']);

package/scripts/lib/config/issue-budget.mjs

@@ -0,0 +1,123 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * issue-budget.mjs — Parser for the `issue-budget:` block-style Session Config key.
+ *
+ * Bounds how many issues ONE session may create. Motivation (measured on the
+ * private instance over four weeks): 1784 issues created against 1285 closed
+ * (net +499), median inter-creation gap 2.6 s, 62 % of creations inside bursts
+ * of >= 5 per minute. The pre-existing `discovery-confidence-threshold` /
+ * `discovery-severity-threshold` knobs do NOT bound this: they are per-finding
+ * QUALITY filters (and the `low` default filters nothing), they are only read
+ * in skill prose, and the largest producers never consult them at all.
+ *
+ * This key is a QUANTITY cap, enforced mechanically by
+ * `hooks/pre-bash-issue-budget.mjs` (shell path) and
+ * `scripts/lib/spiral-carryover.mjs` `runCli()` (programmatic path), both via
+ * `scripts/lib/issue-budget.mjs`.
+ *
+ * Returns `{ "max-per-session", mode, overflow }`.
+ * Tolerant parser: malformed values silently fall back to defaults (the
+ * `reconcile.min-rule-days` posture, NOT the noisier handover-gate WARN) —
+ * a hook must never spam stderr on every single Bash call.
+ *
+ * Consumers: `scripts/lib/config.mjs`, `scripts/lib/issue-budget.mjs`,
+ * `hooks/pre-bash-issue-budget.mjs`, `skills/session-end/SKILL.md` Phase 5.
+ */
+
+/** Valid `mode` values. */
+const MODES = ['strict', 'warn', 'off'];
+
+/** Valid `overflow` values. */
+const OVERFLOW_SINKS = ['collect-issue', 'vault-note'];
+
+/**
+ * Parse the `issue-budget:` block from markdown content.
+ *
+ * Like every sibling block parser this scans the FULL content rather than the
+ * `## Session Config` fence, so the block resolves identically whether it is
+ * nested inside `## Session Config` (the documented home) or lifted to a
+ * top-level block. Bold-bullet headers (`- **issue-budget:**`) are tolerated
+ * via the shared `matchBlockHeader` (#830).
+ *
+ * Defaults:
+ *   max-per-session: 12        integer >= 0; 0 means "no issue may be created"
+ *                              (a valid, deliberately harsh setting). Malformed
+ *                              or negative input falls back to 12.
+ *   mode:            strict    strict | warn | off
+ *   overflow:        collect-issue   collect-issue | vault-note
+ *
+ * YAML shape:
+ *   issue-budget:
+ *     max-per-session: 12
+ *     mode: strict
+ *     overflow: collect-issue
+ *
+ * @param {string} content — full file contents
+ * @returns {{ "max-per-session": number, mode: string, overflow: string }}
+ */
+export function _parseIssueBudget(content) {
+  const defaults = {
+    'max-per-session': 12,
+    mode: 'strict',
+    overflow: 'collect-issue',
+  };
+
+  if (typeof content !== 'string' || content === '') return { ...defaults };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'issue-budget')) inBlock = true;
+      continue;
+    }
+    // Stop at next column-0 non-empty line (sibling top-level key or H2 heading)
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return { ...defaults };
+
+  let maxPerSession = defaults['max-per-session'];
+  let mode = defaults.mode;
+  let overflow = defaults.overflow;
+
+  for (const rawLine of blockLines) {
+    // Strip inline comments and trailing whitespace
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'max-per-session':
+        // Non-negative integer only; a leading '-' fails \d+ → default.
+        if (/^\d+$/.test(v)) maxPerSession = parseInt(v, 10);
+        break;
+
+      case 'mode':
+        if (MODES.includes(v.toLowerCase())) mode = v.toLowerCase();
+        break;
+
+      case 'overflow':
+        if (OVERFLOW_SINKS.includes(v.toLowerCase())) overflow = v.toLowerCase();
+        break;
+    }
+  }
+
+  return {
+    'max-per-session': maxPerSession,
+    mode,
+    overflow,
+  };
+}

package/scripts/lib/config/moc-staleness.mjs

@@ -0,0 +1,98 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * moc-staleness.mjs — Parser for the top-level `moc-staleness:` YAML block.
+ *
+ * Config block shape (see docs/session-config-template.md):
+ *   moc-staleness:
+ *     enabled: false
+ *     thresholds:
+ *       moc: 90
+ *     mode: warn
+ *
+ * Mirrors the docs-staleness.mjs parser design (issue #831) — a single
+ * "moc" tier threshold (days), not a per-tier map like vault-staleness.mjs.
+ *
+ * ZERO IMPORTS other than ./block-header.mjs by design:
+ * tests/lib/config/cycle-guard.test.mjs forbids any scripts/lib/config/*.mjs
+ * from importing ../config.mjs.
+ */
+
+/**
+ * Parse the top-level `moc-staleness:` YAML block from markdown content.
+ * Defaults: enabled=false, thresholds={moc:90}, mode="warn".
+ * @param {string} content — full file contents
+ * @returns {{enabled: boolean, thresholds: {moc: number}, mode: string}}
+ */
+export function _parseMocStaleness(content) {
+  const defaults = {
+    enabled: false,
+    thresholds: { moc: 90 },
+    mode: 'warn',
+  };
+
+  const lines = content.split(/\r?\n/);
+  let inBlock = false;
+  const blockLines = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!inBlock) {
+      if (matchBlockHeader(line, 'moc-staleness')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let msEnabled = false;
+  let msMode = 'warn';
+  const msThresholds = { moc: 90 };
+  let inThresholdsBlock = false;
+
+  for (const rawLine of blockLines) {
+    const clean = rawLine.replace(/\s*#.*$/, '').replace(/\s+$/, '');
+    if (!clean.trim()) continue;
+
+    // Deeper indented key (thresholds sub-keys)
+    const deepMatch = clean.match(/^\s{4,}([a-zA-Z_-]+):\s*(.*)/);
+    if (deepMatch && inThresholdsBlock) {
+      const k = deepMatch[1];
+      let v = deepMatch[2].trim();
+      if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+      else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+      if (k === 'moc') {
+        const n = parseFloat(v);
+        if (Number.isFinite(n) && n > 0) msThresholds[k] = n;
+      }
+      continue;
+    }
+
+    // Top-level key under moc-staleness (2-space indent)
+    const kvMatch = clean.match(/^\s+([a-zA-Z_-]+):\s*(.*)/);
+    if (!kvMatch) continue;
+
+    inThresholdsBlock = false;
+
+    const k = kvMatch[1];
+    let v = kvMatch[2].trim();
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) v = v.slice(1, -1);
+    else if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) v = v.slice(1, -1);
+
+    switch (k) {
+      case 'enabled':
+        msEnabled = v.toLowerCase() === 'true';
+        break;
+      case 'mode':
+        if (['strict', 'warn', 'off'].includes(v)) msMode = v;
+        break;
+      case 'thresholds':
+        inThresholdsBlock = true;
+        break;
+    }
+  }
+
+  return { enabled: msEnabled, thresholds: msThresholds, mode: msMode };
+}

package/scripts/lib/config/reconcile.mjs

@@ -16,6 +16,7 @@ import { matchBlockHeader } from './block-header.mjs';
  *     'confidence-floor': number,
  *     'min-rule-days': number,
  *     'min-insight-chars': number,
+ *     'max-proposals-per-run': number,
  *   }
  *
  * Tolerant parser: malformed values silently fall back to defaults.
@@ -51,6 +52,12 @@ import { matchBlockHeader } from './block-header.mjs';
  *                                          gating the eligibility placeholder-insight check
  *                                          (issue #741.2). Malformed, absent, or negative
  *                                          values fall back to 24.
+ *   reconcile.max-proposals-per-run: 10  — positive integer (min 1); volume brake (issue
+ *                                          #900 D) — the reconcile engine sorts eligible
+ *                                          learnings by confidence DESC and proposes at
+ *                                          most this many per run, recording the cut count
+ *                                          in the run summary (`summary.capped`). Malformed,
+ *                                          absent, or non-positive values fall back to 10.
  *
  * YAML shape:
  *   reconcile:
@@ -61,6 +68,7 @@ import { matchBlockHeader } from './block-header.mjs';
  *     confidence-floor: 0.5
  *     min-rule-days: 7
  *     min-insight-chars: 24
+ *     max-proposals-per-run: 10
  *
  * @param {string} content — full file contents
  * @returns {{
@@ -71,6 +79,7 @@ import { matchBlockHeader } from './block-header.mjs';
  *   'confidence-floor': number,
  *   'min-rule-days': number,
  *   'min-insight-chars': number,
+ *   'max-proposals-per-run': number,
  * }}
  */
 export function _parseReconcile(content) {
@@ -82,6 +91,7 @@ export function _parseReconcile(content) {
     'confidence-floor': 0.5,
     'min-rule-days': 7,
     'min-insight-chars': 24,
+    'max-proposals-per-run': 10,
   };
 
   const lines = content.split(/\r?\n/);
@@ -108,6 +118,7 @@ export function _parseReconcile(content) {
   let confidenceFloor = 0.5;
   let minRuleDays = 7;
   let minInsightChars = 24;
+  let maxProposalsPerRun = 10;
 
   for (const rawLine of blockLines) {
     // Strip inline comments and trailing whitespace
@@ -183,6 +194,15 @@ export function _parseReconcile(content) {
         break;
       }
 
+      case 'max-proposals-per-run': {
+        if (/^\d+$/.test(v)) {
+          const n = parseInt(v, 10);
+          if (n >= 1) maxProposalsPerRun = n;
+          // 0 or malformed: silently ignore, keep default 10
+        }
+        break;
+      }
+
       // targets inline-list with no brackets (e.g. targets: repo-local) — single value
       case 'targets': {
         if (v && !v.startsWith('[')) {
@@ -201,5 +221,6 @@ export function _parseReconcile(content) {
     'confidence-floor': confidenceFloor,
     'min-rule-days': minRuleDays,
     'min-insight-chars': minInsightChars,
+    'max-proposals-per-run': maxProposalsPerRun,
   };
 }

package/scripts/lib/config/section-extractor.mjs

@@ -8,6 +8,126 @@
 // Section extraction (ported from config-yaml-parser.sh)
 // ---------------------------------------------------------------------------
 
+/**
+ * THE canonical predicate for "this line opens the `## Session Config` block".
+ *
+ * Exported (#959 follow-up) because this repo previously carried FIVE
+ * independent copies of this fact, and the loosest of them —
+ * `scripts/lib/claude-md-budget-lint.mjs` — was the module whose whole job is
+ * to MEASURE the block. That asymmetry was not academic: the lint accepted a
+ * heading decorated with a trailing HTML comment (`## Session Config <!-- … -->`,
+ * a decoration this repo's own convention encourages on sibling headings),
+ * while `_extractConfigSection` below rejected it. An author following the
+ * cited convention therefore got a CLAUDE.md (or AGENTS.md on Codex CLI —
+ * transparent aliases, see skills/_shared/instruction-file-resolution.md)
+ * whose every runtime config key
+ * silently fell back to its default, while the lint simultaneously reported
+ * "148 exempt: '## Session Config'" — the instrument affirming the block is
+ * present and runtime-critical at the exact moment the runtime cannot see it.
+ *
+ * The invariant this export exists to hold: **no consumer's predicate may
+ * accept a heading this one rejects.** Importing beats re-deriving; a copy
+ * that drifts loose is worse than no check at all.
+ *
+ * Intentionally EXACT (not a fuzzy regex) apart from CRLF tolerance — it is
+ * the literal comparison `_extractConfigSection` has always used, merely
+ * given a name. `##  Session Config` (two spaces), a trailing HTML comment,
+ * and `## Session Config Convention` are all correctly rejected.
+ *
+ * Dependency note: this module imports NOTHING. Keep it that way — the budget
+ * lint consumes this predicate at bootstrap-scaffold time, before
+ * `.claude/rules/` (or most of the repo) exists.
+ *
+ * @param {string} line - a single line, with or without a trailing '\r'.
+ * @returns {boolean}
+ */
+export function isSessionConfigHeading(line) {
+  return typeof line === 'string' && line.replace(/\r$/, '') === SESSION_CONFIG_HEADING;
+}
+
+/**
+ * The literal heading text, for the one site that legitimately WRITES it
+ * (`scripts/lib/ecosystem-wizard/config-writer.mjs` appends a fresh
+ * `## Session Config` section when none exists).
+ *
+ * A producer and a comparator agreeing by coincidence is the same disease
+ * `isSessionConfigHeading` exists to cure, one level down: a writer that
+ * emits a heading the reader rejects manufactures exactly the silent
+ * everything-falls-back-to-defaults failure described above. Writers import
+ * this; comparators import the predicate. Neither re-types the string.
+ *
+ * @type {string}
+ */
+export const SESSION_CONFIG_HEADING = '## Session Config';
+
+/**
+ * Locate the `## Session Config` block and return its body span.
+ *
+ * THE canonical block-extractor, and the companion to
+ * `isSessionConfigHeading` above. Four consumers previously re-derived this
+ * span with four different regexes, and the divergence was not academic:
+ * `harness-audit/categories/category4.mjs` used
+ * `/^## Session Config\s*\n([\s\S]*?)(?=^## |\s*$)/m`, whose `\s*$` lookahead
+ * (with `/m`, `$` matches at every line end) makes the lazy body quantifier
+ * stop at the FIRST line of the block. On this repo's own CLAUDE.md that
+ * captured 17 characters — `persistence: true` — instead of 2877, so the
+ * `vault-integration:` block three lines below was structurally invisible and
+ * the c4.4 check scored 2/2 with "vault-integration not enabled — skip" in a
+ * repo where it is enabled. A capture bug in a scoring instrument reads as a
+ * pass, never as an error.
+ *
+ * The body runs from the line AFTER the heading up to (not including) the
+ * next `## ` heading, or EOF. Line-based over `isSessionConfigHeading`, so
+ * the heading predicate cannot drift from the span extractor.
+ *
+ * Offsets are indices into the ORIGINAL `content` string, so callers that
+ * need to splice (insert/replace) can do so without re-finding the block.
+ *
+ * @param {string} content - full markdown document
+ * @param {{ occurrence?: 'first'|'last' }} [options] - which heading to match
+ *   when a document carries several (docs/session-config-template.md carries
+ *   two, both inside fenced examples).
+ * @returns {{ body: string, bodyStart: number, bodyEnd: number,
+ *   headingLine: number } | null} null when no heading matches.
+ */
+export function findSessionConfigBlock(content, { occurrence = 'first' } = {}) {
+  if (typeof content !== 'string' || content.length === 0) return null;
+
+  const lines = content.split('\n');
+
+  // Byte offset of the start of each line in `content`.
+  const lineStarts = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineStarts.push(offset);
+    offset += line.length + 1; // +1 for the '\n' consumed by split
+  }
+
+  const headingIdxs = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (isSessionConfigHeading(lines[i])) headingIdxs.push(i);
+  }
+  if (headingIdxs.length === 0) return null;
+
+  const targetIdx = occurrence === 'last' ? headingIdxs[headingIdxs.length - 1] : headingIdxs[0];
+
+  // Body ends at the next `## ` heading (any H2 closes the block), or EOF.
+  let endIdx = lines.length;
+  for (let i = targetIdx + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i].replace(/\r$/, ''))) { endIdx = i; break; }
+  }
+
+  const bodyStart = targetIdx + 1 < lines.length ? lineStarts[targetIdx + 1] : content.length;
+  const bodyEnd = endIdx < lines.length ? lineStarts[endIdx] : content.length;
+
+  return {
+    body: lines.slice(targetIdx + 1, endIdx).join('\n'),
+    bodyStart,
+    bodyEnd,
+    headingLine: targetIdx + 1, // 1-based, for error reporting
+  };
+}
+
 /**
  * Extract the raw ## Session Config block lines from markdown content.
  * - CRLF-tolerant
@@ -24,7 +144,7 @@ export function _extractConfigSection(content) {
   for (const rawLine of lines) {
     const line = rawLine.replace(/\r$/, '');
 
-    if (line === '## Session Config') {
+    if (isSessionConfigHeading(line)) {
       inSection = true;
       continue;
     }