session-orchestrator 3.16.0 → 3.17.0

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/worktree-orphans.mjs

@@ -0,0 +1,138 @@
+import { matchBlockHeader } from './block-header.mjs';
+
+/**
+ * worktree-orphans.mjs — Parser for the top-level `worktree-orphans:` YAML block.
+ *
+ * Config block shape (see docs/session-config-template.md):
+ *   worktree-orphans:
+ *     enabled: false
+ *     base-branch: main
+ *     mode: warn
+ *
+ * Mirrors the docs-staleness.mjs parser design (issue #831 / B5), but flat —
+ * there is no nested threshold map, just three scalar keys.
+ *
+ * Opt-in by design: `enabled` defaults to `false`, so a repo that has never
+ * heard of this block never pays a single git invocation for it.
+ *
+ * ZERO IMPORTS beyond ./block-header.mjs: tests/lib/config/cycle-guard.test.mjs
+ * forbids any scripts/lib/config/*.mjs from importing ../config.mjs.
+ */
+
+/**
+ * Valid `base-branch` character set — mirrors `ENTER_WORKTREE_BRANCH_RE` in
+ * scripts/lib/autopilot/worktree-pipeline.mjs (itself mirroring the private
+ * `isValidBranch()` in scripts/lib/session-id.mjs). Duplicated rather than
+ * imported because this parser is dependency-free by contract (see header) and
+ * `isValidBranch` is module-private; worktree-pipeline.mjs sets the precedent
+ * for mirroring it locally.
+ */
+const BASE_BRANCH_CHARSET = /^[A-Za-z0-9._/-]+$/;
+
+/**
+ * Decide whether a `base-branch` value is safe to hand to the Phase 4b sweep.
+ *
+ * The consumer (scripts/lib/session-end/worktree-orphan-sweep.mjs) interpolates
+ * this value into the argv token `` `${baseBranch}..${branch}` `` for
+ * `git rev-list --count`. Two failure modes make a charset check load-bearing:
+ *
+ *  1. OPTION-SHAPED values. `git rev-list` parses a leading-`-` token as an
+ *     OPTION, not a revision. `--glob=refs/heads/*` makes rev-list answer about
+ *     a completely different ref set and exit 0 with `0` — a silent WRONG
+ *     answer, not an error, so the sweep's conservative-on-error guard never
+ *     fires and every worktree is reported as a 0-ahead orphan.
+ *  2. RANGE-CORRUPTING values. A value containing `..` yields `a..b..branch`.
+ *
+ * No shell-out: `git check-ref-format --branch` is the semantic reference, but
+ * a config parser must stay a pure function. The charset + prefix/suffix rules
+ * below are a conservative SUBSET of what git accepts — a rejected value falls
+ * back to the `main` default rather than failing the parse, because a
+ * mistyped branch name must never escalate into a broken session config.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function _isSafeBaseBranch(v) {
+  if (typeof v !== 'string' || v.length === 0) return false;
+  // Rejects whitespace and every shell-ish character (= * ; | & $ ` ' " ( ) < >),
+  // which also rejects `--glob=refs/heads/*` on the `=` and `*` alone.
+  if (!BASE_BRANCH_CHARSET.test(v)) return false;
+  // The charset permits `-` so that `my-branch` works; a LEADING `-` is the
+  // option-shaped case and must be rejected explicitly.
+  if (v.startsWith('-')) return false;
+  // Would corrupt the `<base>..<branch>` range token at the sink.
+  if (v.includes('..')) return false;
+  // git check-ref-format: no leading/trailing `/` or `.`, no `.lock` suffix.
+  if (v.startsWith('/') || v.endsWith('/')) return false;
+  if (v.startsWith('.') || v.endsWith('.')) return false;
+  if (v.endsWith('.lock')) return false;
+  return true;
+}
+
+/**
+ * Parse the top-level `worktree-orphans:` YAML block from markdown content.
+ * Defaults: enabled=false, base-branch="main", mode="warn".
+ *
+ * @param {string} content — full file contents
+ * @returns {{enabled: boolean, 'base-branch': string, mode: string}}
+ */
+export function _parseWorktreeOrphans(content) {
+  const defaults = {
+    enabled: false,
+    'base-branch': 'main',
+    mode: 'warn',
+  };
+
+  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) {
+      // #830: bold-tolerant header match — never a hand-rolled regex.
+      if (matchBlockHeader(line, 'worktree-orphans')) inBlock = true;
+      continue;
+    }
+    if (line.length > 0 && !/^\s/.test(line)) break;
+    blockLines.push(line);
+  }
+
+  if (blockLines.length === 0) return defaults;
+
+  let woEnabled = false;
+  let woBaseBranch = 'main';
+  let woMode = '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':
+        woEnabled = v.toLowerCase() === 'true';
+        break;
+      case 'base-branch':
+        // NOT "any non-empty scalar": an option-shaped or range-corrupting
+        // value is silently dropped in favour of the safe `main` default.
+        // See _isSafeBaseBranch() for why this is a security boundary.
+        if (_isSafeBaseBranch(v)) woBaseBranch = v;
+        break;
+      case 'mode':
+        if (['warn', 'off'].includes(v)) woMode = v;
+        break;
+    }
+  }
+
+  return { enabled: woEnabled, 'base-branch': woBaseBranch, mode: woMode };
+}

package/scripts/lib/config.mjs

@@ -8,6 +8,9 @@
  *   drift-check.mjs       — _parseDriftCheck
  *   docs-orchestrator.mjs — _parseDocsOrchestrator
  *   vault-staleness.mjs   — _parseVaultStaleness
+ *   moc-staleness.mjs     — _parseMocStaleness
+ *   context-coverage.mjs  — _parseContextCoverage
+ *   worktree-orphans.mjs  — _parseWorktreeOrphans
  *   events-rotation.mjs   — _parseEventsRotation
  *   vault-integration.mjs — _parseVaultIntegration + _parseResourceThresholds
  *
@@ -38,6 +41,9 @@ import { _parseDriftCheck } from './config/drift-check.mjs';
 import { _parseDocsOrchestrator } from './config/docs-orchestrator.mjs';
 import { _parseVaultStaleness } from './config/vault-staleness.mjs';
 import { _parseDocsStaleness } from './config/docs-staleness.mjs';
+import { _parseMocStaleness } from './config/moc-staleness.mjs';
+import { _parseContextCoverage } from './config/context-coverage.mjs';
+import { _parseWorktreeOrphans } from './config/worktree-orphans.mjs';
 import { _parseEventsRotation } from './config/events-rotation.mjs';
 import { _parseVaultIntegration, _parseResourceThresholds } from './config/vault-integration.mjs';
 import { _parseTest } from './config/test.mjs';
@@ -262,6 +268,12 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
   const vaultStaleness = _parseVaultStaleness(mdContent);
   // docs-staleness: parsed from full content (standalone top-level block, #781)
   const docsStaleness = _parseDocsStaleness(mdContent);
+  // moc-staleness: parsed from full content (standalone top-level block, #831/B2)
+  const mocStaleness = _parseMocStaleness(mdContent);
+  // context-coverage: parsed from full content (standalone top-level block, #831/B4)
+  const contextCoverage = _parseContextCoverage(mdContent);
+  // worktree-orphans: parsed from full content (standalone top-level block, #831/B5)
+  const worktreeOrphans = _parseWorktreeOrphans(mdContent);
 
   // events-rotation: parsed from full content (standalone top-level block)
   const eventsRotation = _parseEventsRotation(mdContent);
@@ -449,6 +461,9 @@ export function parseSessionConfig(mdContent, { hostPaths } = {}) {
     'docs-orchestrator': docsOrchestrator,
     'vault-staleness': vaultStaleness,
     'docs-staleness': docsStaleness,
+    'moc-staleness': mocStaleness,
+    'context-coverage': contextCoverage,
+    'worktree-orphans': worktreeOrphans,
     'events-rotation': eventsRotation,
     'test': testConfig,
     'gitlab-portfolio': gitlabPortfolio,

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

@@ -0,0 +1,223 @@
+/**
+ * context-coverage-banner.mjs — Session-start banner for issue #831 (building
+ * block B4).
+ *
+ * Surfaces a `warn` banner during session-start Phase 4 when a REGISTERED
+ * vault project — a `<vaultDir>/01-projects/<slug>/` directory that contains
+ * an `_overview.md` — has neither a `context.md` nor a `_passive.md` file. A
+ * manual audit found 11 such gap folders in one vault; this probe makes the
+ * gap mechanically visible at session-start instead of relying on manual
+ * sweeps.
+ *
+ * "Registered" is deliberately NOT reinvented here. `discoverVaultRepos()`
+ * (`scripts/lib/gitlab-portfolio/vcs-detect.mjs`) already establishes the
+ * exact convention this probe reuses: a `01-projects/<slug>/` directory
+ * without an `_overview.md` is silently skipped — it is not a project, and
+ * therefore it can never be a "gap".
+ *
+ * Design notes:
+ *  - Mirrors the contract used by every other Phase 4 banner
+ *    (`scripts/lib/vault-staleness-banner.mjs`, `scripts/lib/loop-readiness-banner.mjs`,
+ *    `scripts/lib/reconcile-nudge-banner.mjs`): a single `checkXxx()` entry
+ *    point that returns `null` (silent no-op) or `{ severity, message, ... }`
+ *    — never an array, never `undefined`, never a throw.
+ *  - Synchronous — the probe only touches `existsSync`/`readdirSync`/`statSync`,
+ *    so unlike the async peer-cards/reconcile-nudge probes this one needs no
+ *    `await` at the call site (mirrors `checkLoopReadiness`).
+ *  - Never throws. Wrapped in an outermost defensive `try/catch`; every
+ *    individually-fallible filesystem call additionally gets its own inner
+ *    bare (no-binding) catch with a one-line explanatory comment.
+ *  - `vault-dir` resolution mirrors the host-local-override pattern used
+ *    throughout the plugin (issue #653): an injected `opts.vaultDir` test
+ *    seam wins, then `config['vault-integration']['vault-dir']`, else the
+ *    probe silently no-ops (no vault configured — nothing to check).
+ *  - The committed repo default for `vault-integration.vault-dir` is
+ *    tilde-prefixed (`~/Projects/vault`) and is NOT pre-expanded anywhere
+ *    upstream of this module — `expandTilde()` from `./common.mjs` is applied
+ *    unconditionally before the first `path.join`, exactly as
+ *    `discoverVaultRepos()` does inline for the same reason.
+ *
+ * Cross-references:
+ *  - `scripts/lib/gitlab-portfolio/vcs-detect.mjs` (`discoverVaultRepos`) —
+ *    the canonical "registered" definition this probe reuses.
+ *  - `scripts/lib/config/context-coverage.mjs` (`_parseContextCoverage`) —
+ *    the `context-coverage:` Session Config block parser. NOT wired into
+ *    `scripts/lib/config.mjs` by this module — the coordinator registers it
+ *    separately. The exact lines to add there:
+ *
+ *      import { _parseContextCoverage } from './config/context-coverage.mjs';
+ *      // ... later, alongside the other top-level block parses:
+ *      const contextCoverage = _parseContextCoverage(mdContent);
+ *      // ... in the returned config object:
+ *      'context-coverage': contextCoverage,
+ *
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site (wiring
+ *    snippet supplied separately; this module does not edit that file).
+ *  - Issue #831 (building block B4).
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { expandTilde } from './common.mjs';
+
+/** Vault-relative projects directory (mirrors discoverVaultRepos()'s own constant). */
+const PROJECTS_SUBDIR = '01-projects';
+
+/** File marking a `01-projects/<slug>/` directory as REGISTERED (discoverVaultRepos() convention). */
+const OVERVIEW_FILE = '_overview.md';
+
+/** Either file's presence satisfies "coverage" for a registered project. */
+const COVERAGE_FILES = ['context.md', '_passive.md'];
+
+/**
+ * Above this many gap slugs, the message truncates the name list and says so
+ * explicitly rather than silently dropping names past the limit.
+ */
+const MAX_GAP_NAMES_IN_MESSAGE = 20;
+
+/**
+ * Resolve the vault directory to scan.
+ *
+ * Precedence: `opts.vaultDir` (test seam) > `config['vault-integration']['vault-dir']` > null.
+ *
+ * @param {string|undefined} vaultDir
+ * @param {unknown} config
+ * @returns {string|null} raw (not-yet-tilde-expanded) vault dir, or null when unresolvable
+ */
+function _resolveRawVaultDir(vaultDir, config) {
+  if (typeof vaultDir === 'string' && vaultDir.length > 0) return vaultDir;
+
+  if (config && typeof config === 'object') {
+    const vaultIntegration = /** @type {Record<string, unknown>} */ (config)['vault-integration'];
+    if (vaultIntegration && typeof vaultIntegration === 'object') {
+      const raw = /** @type {Record<string, unknown>} */ (vaultIntegration)['vault-dir'];
+      if (typeof raw === 'string' && raw.length > 0) return raw;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Format the gap-slug list for the banner message, truncating (with an
+ * explicit note) past `MAX_GAP_NAMES_IN_MESSAGE`.
+ *
+ * @param {string[]} slugs
+ * @returns {string}
+ */
+function _formatGapNames(slugs) {
+  if (slugs.length <= MAX_GAP_NAMES_IN_MESSAGE) return slugs.join(', ');
+  const shown = slugs.slice(0, MAX_GAP_NAMES_IN_MESSAGE).join(', ');
+  const hiddenCount = slugs.length - MAX_GAP_NAMES_IN_MESSAGE;
+  return `${shown}, and ${hiddenCount} more (name list truncated)`;
+}
+
+/**
+ * Check context-coverage and produce a session-start banner.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.repoRoot] — REQUIRED absolute path to the repo root.
+ * @param {string} [opts.vaultDir] — test seam; overrides the config-resolved vault dir.
+ * @param {object} [opts.config] — optional already-parsed Session Config (avoids
+ *   a second CLAUDE.md (or AGENTS.md on Codex CLI) read; caller passes `$CONFIG`, mirrors `checkReconcileNudge`).
+ *   Read keys: `config['context-coverage']` (`.enabled`, `.mode`) and
+ *   `config['vault-integration']['vault-dir']`.
+ * @returns {null | {severity: 'warn', message: string, gaps: Array<{slug: string}>, registered: number, covered: number}}
+ */
+export function checkContextCoverage({ repoRoot, vaultDir, config } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const cfg =
+      config &&
+      typeof config === 'object' &&
+      config['context-coverage'] &&
+      typeof config['context-coverage'] === 'object'
+        ? config['context-coverage']
+        : {};
+
+    // Config gate — returns null BEFORE any filesystem I/O. Explicit opt-in
+    // required: `cfg.enabled` must be the literal `true`, not merely
+    // truthy/absent. A config block that is entirely absent (or present
+    // without an `enabled` key) must fail CLOSED, not open — see issue #831
+    // fail-open regression (a config carrying `vault-integration.vault-dir`
+    // but no `context-coverage` block previously ran the probe unsolicited,
+    // because `undefined !== false`).
+    if (cfg?.enabled !== true || cfg?.mode === 'off') return null;
+
+    const rawVaultDir = _resolveRawVaultDir(vaultDir, config);
+    if (!rawVaultDir) return null;
+
+    const resolvedVaultDir = expandTilde(rawVaultDir);
+    const projectsDir = path.join(resolvedVaultDir, PROJECTS_SUBDIR);
+
+    let entries;
+    try {
+      entries = readdirSync(projectsDir);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(entries) || entries.length === 0) return null;
+
+    entries = [...entries].sort();
+
+    let registered = 0;
+    const gaps = [];
+
+    for (const entry of entries) {
+      if (typeof entry !== 'string' || entry.startsWith('.')) continue;
+
+      const entryPath = path.join(projectsDir, entry);
+
+      let stat;
+      try {
+        stat = statSync(entryPath);
+      } catch {
+        continue;
+      }
+      if (!stat || !stat.isDirectory()) continue;
+
+      // "Registered" is defined ELSEWHERE (discoverVaultRepos()) — a
+      // directory lacking `_overview.md` is not a project, and therefore not
+      // a gap. Do not invent a second definition here.
+      let hasOverview = false;
+      try {
+        hasOverview = existsSync(path.join(entryPath, OVERVIEW_FILE));
+      } catch {
+        // best-effort — treat an unreadable path as "no _overview.md".
+      }
+      if (!hasOverview) continue;
+
+      registered += 1;
+
+      let isCovered = false;
+      for (const file of COVERAGE_FILES) {
+        try {
+          if (existsSync(path.join(entryPath, file))) {
+            isCovered = true;
+            break;
+          }
+        } catch {
+          // best-effort — treat an unreadable path as "not covered by this file".
+        }
+      }
+
+      if (!isCovered) gaps.push({ slug: entry });
+    }
+
+    if (registered === 0 || gaps.length === 0) return null;
+
+    const covered = registered - gaps.length;
+    const gapSlugs = gaps.map((g) => g.slug);
+
+    const finding = `${gaps.length} of ${registered} registered projects lack context.md and _passive.md`;
+    const remediation = 'add a context.md or mark the project passive with _passive.md.';
+    const message = `⚠ context-coverage: ${finding} — ${_formatGapNames(gapSlugs)} — ${remediation}`;
+
+    return { severity: 'warn', message, gaps, registered, covered };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}