session-orchestrator 3.16.0

package/skills/discovery/probes/vault-narrative-staleness.mjs

@@ -0,0 +1,355 @@
+/**
+ * skills/discovery/probes/vault-narrative-staleness.mjs
+ *
+ * Probe: detects stale vault narratives — context.md / decisions.md / people.md
+ * files whose `updated` frontmatter field is older than the tier threshold.
+ *
+ * Tier thresholds (days):
+ *   top      = 30
+ *   active   = 60  (default when tier is missing or unrecognised)
+ *   archived = 180
+ *
+ * Tier is read from the project's `_overview.md` frontmatter `tier:` field.
+ * If `_overview.md` is absent, unreadable, or has no `tier` field, the probe
+ * falls back to `active` (60 days).
+ *
+ * Severity escalation relative to threshold T:
+ *   age_days > T * 3  → high
+ *   age_days > T * 2  → medium
+ *   age_days > T      → low
+ *
+ * Missing `updated` field → low / confidence 0.7.
+ * Parse errors           → low / confidence 0.6 (errors counter incremented).
+ */
+
+import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const NARRATIVE_FILES = ['context.md', 'decisions.md', 'people.md'];
+
+const TIER_THRESHOLDS = {
+  top: 30,
+  active: 60,
+  archived: 180,
+};
+
+const VALID_TIERS = new Set(Object.keys(TIER_THRESHOLDS));
+const DEFAULT_TIER = 'active';
+
+// ---------------------------------------------------------------------------
+// Minimal YAML frontmatter parser — top-level scalar key: value only.
+// Handles: plain strings, numbers, quoted strings (single + double).
+// Does not handle nested mappings, sequences, or block scalars.
+// Returns null if no frontmatter block found.
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!m) return null;
+  const block = m[1];
+  const result = {};
+  for (const line of block.split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)/);
+    if (!kv) continue;
+    const key = kv[1];
+    let val = kv[2].trim();
+    // Strip surrounding quotes
+    if (
+      (val.startsWith('"') && val.endsWith('"') && val.length >= 2) ||
+      (val.startsWith("'") && val.endsWith("'") && val.length >= 2)
+    ) {
+      val = val.slice(1, -1);
+    }
+    result[key] = val;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function resolveVaultDir(projectRoot, config) {
+  if (config?.['vault-integration']?.['vault-dir']) return config['vault-integration']['vault-dir'];
+  if (process.env.VAULT_DIR) return process.env.VAULT_DIR;
+  return null;
+}
+
+function readTier(projectDir, _slug) {
+  const overviewPath = join(projectDir, '_overview.md');
+  if (!existsSync(overviewPath)) return DEFAULT_TIER;
+  let raw;
+  try {
+    raw = readFileSync(overviewPath, 'utf8');
+  } catch {
+    return DEFAULT_TIER;
+  }
+  let fm;
+  try {
+    fm = parseFrontmatter(raw);
+  } catch {
+    return DEFAULT_TIER;
+  }
+  if (!fm) return DEFAULT_TIER;
+  const tier = fm.tier ? fm.tier.toLowerCase() : null;
+  return tier && VALID_TIERS.has(tier) ? tier : DEFAULT_TIER;
+}
+
+function computeSeverity(ageDays, threshold) {
+  if (ageDays > threshold * 3) return 'high';
+  if (ageDays > threshold * 2) return 'medium';
+  return 'low';
+}
+
+function makeMetricsPath(projectRoot) {
+  return join(projectRoot, '.orchestrator', 'metrics');
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} projectRoot  Absolute path to the consumer project root.
+ * @param {object} config       Parsed Session Config (may be empty / partial).
+ * @returns {Promise<object>}   { findings, metrics, duration_ms [, skipped_reason] }
+ */
+export async function runProbe(projectRoot, config) {
+  const startMs = Date.now();
+
+  try {
+    // ── Early exit: vault-dir not configured ──────────────────────────────────
+    const vaultDir = resolveVaultDir(projectRoot, config);
+    if (!vaultDir) {
+      return {
+        findings: [],
+        metrics: { scanned_projects: 0, scanned_narratives: 0, stale_narratives: 0, errors: 0 },
+        duration_ms: Date.now() - startMs,
+        skipped_reason: 'vault-dir not configured',
+      };
+    }
+
+    // ── Early exit: vault-dir does not exist ──────────────────────────────────
+    if (!existsSync(vaultDir)) {
+      return {
+        findings: [],
+        metrics: { scanned_projects: 0, scanned_narratives: 0, stale_narratives: 0, errors: 0 },
+        duration_ms: Date.now() - startMs,
+        skipped_reason: 'vault-dir not found on disk',
+      };
+    }
+
+    const projectsDir = join(vaultDir, '01-projects');
+
+    // ── Early exit: 01-projects subdir absent ─────────────────────────────────
+    if (!existsSync(projectsDir)) {
+      return {
+        findings: [],
+        metrics: { scanned_projects: 0, scanned_narratives: 0, stale_narratives: 0, errors: 0 },
+        duration_ms: Date.now() - startMs,
+        skipped_reason: '01-projects not found in vault',
+      };
+    }
+
+    // ── Scan ──────────────────────────────────────────────────────────────────
+    const now = Date.now();
+    const findings = [];
+    let scannedProjects = 0;
+    let scannedNarratives = 0;
+    let staleNarratives = 0;
+    let errors = 0;
+
+    let projectEntries;
+    try {
+      projectEntries = readdirSync(projectsDir, { withFileTypes: true });
+    } catch (err) {
+      return {
+        findings: [],
+        metrics: { scanned_projects: 0, scanned_narratives: 0, stale_narratives: 0, errors: 1 },
+        duration_ms: Date.now() - startMs,
+        skipped_reason: `cannot read 01-projects: ${err.message || err}`,
+      };
+    }
+
+    for (const entry of projectEntries) {
+      if (!entry.isDirectory()) continue;
+      const slug = entry.name;
+      const projectDir = join(projectsDir, slug);
+
+      scannedProjects++;
+
+      const tier = readTier(projectDir, slug);
+      const threshold = TIER_THRESHOLDS[tier];
+
+      for (const narrativeFile of NARRATIVE_FILES) {
+        const filePath = join(projectDir, narrativeFile);
+        if (!existsSync(filePath)) continue;
+
+        scannedNarratives++;
+
+        // Read file
+        let raw;
+        try {
+          raw = readFileSync(filePath, 'utf8');
+        } catch (err) {
+          findings.push({
+            severity: 'low',
+            confidence: 0.6,
+            title: `[vault-narrative-staleness] ${slug}/${narrativeFile}: cannot read file`,
+            evidence: { slug, tier, file: narrativeFile, error: err.message || String(err) },
+          });
+          errors++;
+          continue;
+        }
+
+        // Parse frontmatter
+        let fm;
+        try {
+          fm = parseFrontmatter(raw);
+        } catch (err) {
+          findings.push({
+            severity: 'low',
+            confidence: 0.6,
+            title: `[vault-narrative-staleness] ${slug}/${narrativeFile}: frontmatter parse error`,
+            evidence: { slug, tier, file: narrativeFile, error: err.message || String(err) },
+          });
+          errors++;
+          continue;
+        }
+
+        if (!fm) {
+          // No frontmatter block at all — treat same as missing updated
+          findings.push({
+            severity: 'low',
+            confidence: 0.7,
+            title: `[vault-narrative-staleness] ${slug}/${narrativeFile}: updated field missing`,
+            evidence: {
+              slug,
+              tier,
+              file: narrativeFile,
+              updated: null,
+              age_days: null,
+              threshold_days: threshold,
+            },
+          });
+          continue;
+        }
+
+        const updatedRaw = fm.updated;
+        if (!updatedRaw) {
+          findings.push({
+            severity: 'low',
+            confidence: 0.7,
+            title: `[vault-narrative-staleness] ${slug}/${narrativeFile}: updated field missing`,
+            evidence: {
+              slug,
+              tier,
+              file: narrativeFile,
+              updated: null,
+              age_days: null,
+              threshold_days: threshold,
+            },
+          });
+          continue;
+        }
+
+        // Parse date
+        const updatedMs = Date.parse(updatedRaw);
+        if (Number.isNaN(updatedMs)) {
+          findings.push({
+            severity: 'low',
+            confidence: 0.6,
+            title: `[vault-narrative-staleness] ${slug}/${narrativeFile}: updated field not a valid date`,
+            evidence: {
+              slug,
+              tier,
+              file: narrativeFile,
+              updated: updatedRaw,
+              age_days: null,
+              threshold_days: threshold,
+            },
+          });
+          errors++;
+          continue;
+        }
+
+        const ageDays = (now - updatedMs) / 86400000;
+
+        if (ageDays > threshold) {
+          staleNarratives++;
+          const ageDaysRounded = Math.round(ageDays);
+          const severity = computeSeverity(ageDays, threshold);
+          findings.push({
+            severity,
+            confidence: 0.9,
+            title: `[vault-narrative-staleness] ${slug}/${narrativeFile}: ${ageDaysRounded}d since update (${tier} threshold: ${threshold}d)`,
+            evidence: {
+              slug,
+              tier,
+              file: narrativeFile,
+              updated: updatedRaw,
+              age_days: ageDaysRounded,
+              threshold_days: threshold,
+            },
+          });
+        }
+      }
+    }
+
+    const durationMs = Date.now() - startMs;
+    const metrics = {
+      scanned_projects: scannedProjects,
+      scanned_narratives: scannedNarratives,
+      stale_narratives: staleNarratives,
+      errors,
+    };
+
+    // ── JSONL append ──────────────────────────────────────────────────────────
+    try {
+      const metricsDir = makeMetricsPath(projectRoot);
+      if (!existsSync(metricsDir)) mkdirSync(metricsDir, { recursive: true });
+      const record = {
+        timestamp: new Date().toISOString(),
+        probe: 'vault-narrative-staleness',
+        project_root: projectRoot,
+        vault_dir: vaultDir,
+        scanned_projects: scannedProjects,
+        scanned_narratives: scannedNarratives,
+        stale_narratives: staleNarratives,
+        errors,
+        duration_ms: durationMs,
+        findings: findings.map((f) => ({
+          slug: f.evidence.slug,
+          file: f.evidence.file,
+          tier: f.evidence.tier,
+          severity: f.severity,
+          age_days: f.evidence.age_days,
+          threshold_days: f.evidence.threshold_days,
+        })),
+      };
+      appendFileSync(
+        join(metricsDir, 'vault-narrative-staleness.jsonl'),
+        JSON.stringify(record) + '\n',
+        'utf8',
+      );
+    } catch {
+      // JSONL write failure is non-fatal — probe result is still returned
+    }
+
+    return { findings, metrics, duration_ms: durationMs };
+  } catch (err) {
+    // Top-level safety net — probe must never throw
+    return {
+      findings: [],
+      metrics: { scanned_projects: 0, scanned_narratives: 0, stale_narratives: 0, errors: 1 },
+      duration_ms: Date.now() - startMs,
+      skipped_reason: `probe error: ${err.message || err}`,
+    };
+  }
+}
+
+export default runProbe;

package/skills/discovery/probes/vault-staleness.mjs

@@ -0,0 +1,272 @@
+/**
+ * skills/discovery/probes/vault-staleness.mjs
+ *
+ * Probe: detects stale vault mirroring — projects where the upstream repo
+ * has advanced past the last vault sync. Threshold: 24 hours.
+ *
+ * Input: projectRoot (absolute path to the repo running discovery), config
+ * (parsed Session Config object). Reads vault-integration.vault-dir from config.
+ *
+ * Output: {findings[], metrics, duration_ms, [skipped_reason]}. Never throws.
+ * Also appends one JSONL summary record to .orchestrator/metrics/vault-staleness.jsonl.
+ *
+ * Current limitation: we compare lastSync age against probe run time only —
+ * not against the upstream repo's most-recent commit. Mapping vault slugs to
+ * local repo paths is not reliably available from the probe's inputs. A future
+ * iteration should resolve each slug to a repo path and run
+ * `git log -1 --format=%aI` to obtain the true lastCommit timestamp, then
+ * compute |lastCommit - lastSync| instead.
+ */
+
+import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Minimal YAML frontmatter parser — top-level scalar fields only (<30 lines).
+// Strips surrounding quotes from values. Skips list items (lines starting "- ").
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(text) {
+  const lines = text.split(/\r?\n/);
+  let start = -1;
+  let end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      if (start === -1) { start = i; }
+      else { end = i; break; }
+    }
+  }
+  if (start === -1 || end === -1) return null;
+  const fm = {};
+  for (let i = start + 1; i < end; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith('#') || line.trimStart().startsWith('- ')) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    let val = line.slice(colon + 1).trim();
+    // Strip surrounding quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    fm[key] = val;
+  }
+  return fm;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const HOURS_24 = 24 * 60 * 60 * 1000;
+const HOURS_168 = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+function deltaHours(ms) {
+  return Math.round(ms / (60 * 60 * 1000) * 10) / 10;
+}
+
+function formatDelta(ms) {
+  const h = ms / (60 * 60 * 1000);
+  if (h < 48) return `${Math.round(h * 10) / 10}h`;
+  return `${Math.round(h / 24 * 10) / 10}d`;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+export async function runProbe(projectRoot, config) {
+  const start = Date.now();
+
+  const makeSkip = (skipped_reason) => ({
+    findings: [],
+    metrics: { scanned_projects: 0, stale_count: 0, errors: 0 },
+    duration_ms: Math.round(Date.now() - start),
+    skipped_reason,
+  });
+
+  try {
+    // --- Config validation (early exit paths) ---
+
+    const vaultDir = config?.['vault-integration']?.['vault-dir'];
+    if (!vaultDir) {
+      return makeSkip('vault-dir not configured');
+    }
+
+    if (!existsSync(vaultDir)) {
+      return makeSkip(`vault-dir does not exist: ${vaultDir}`);
+    }
+
+    const projectsDir = join(vaultDir, '01-projects');
+    if (!existsSync(projectsDir)) {
+      return makeSkip('01-projects directory missing in vault');
+    }
+
+    // --- Scan loop ---
+
+    const findings = [];
+    const metrics = { scanned_projects: 0, stale_count: 0, errors: 0 };
+    const now = Date.now();
+
+    let entries;
+    try {
+      entries = readdirSync(projectsDir, { withFileTypes: true });
+    } catch (err) {
+      return {
+        findings: [{
+          severity: 'medium',
+          confidence: 0.5,
+          title: '[vault-staleness] probe error',
+          description: err.message,
+          evidence: {},
+        }],
+        metrics: { scanned_projects: 0, stale_count: 0, errors: 1 },
+        duration_ms: Math.round(Date.now() - start),
+        error: err.message,
+      };
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const overviewPath = join(projectsDir, entry.name, '_overview.md');
+      if (!existsSync(overviewPath)) continue; // non-project dir, skip silently
+
+      metrics.scanned_projects++;
+
+      let text;
+      try {
+        text = readFileSync(overviewPath, 'utf8');
+      } catch (err) {
+        metrics.errors++;
+        findings.push({
+          severity: 'low',
+          confidence: 0.6,
+          file_path: overviewPath,
+          title: `[vault-staleness] ${entry.name}: could not read _overview.md`,
+          description: err.message,
+          evidence: { slug: entry.name, tier: undefined, lastSync: undefined, delta_hours: undefined },
+        });
+        continue;
+      }
+
+      let fm;
+      try {
+        fm = parseFrontmatter(text);
+      } catch {
+        fm = null;
+      }
+
+      if (!fm) {
+        metrics.errors++;
+        findings.push({
+          severity: 'low',
+          confidence: 0.6,
+          file_path: overviewPath,
+          title: `[vault-staleness] ${entry.name}: missing or malformed frontmatter`,
+          description: 'Could not parse YAML frontmatter from _overview.md',
+          evidence: { slug: entry.name, tier: undefined, lastSync: undefined, delta_hours: undefined },
+        });
+        continue;
+      }
+
+      const slug = fm.slug || entry.name;
+      const tier = fm.tier || undefined;
+      const lastSync = fm.lastSync || undefined;
+
+      if (!lastSync) {
+        metrics.stale_count++;
+        findings.push({
+          severity: 'medium',
+          confidence: 0.8,
+          file_path: overviewPath,
+          title: `[vault-staleness] ${slug}: lastSync missing from frontmatter`,
+          description: 'The _overview.md has no lastSync field — vault sync status is unknown.',
+          evidence: { slug, tier, lastSync: undefined, delta_hours: undefined },
+        });
+        continue;
+      }
+
+      // Parse lastSync as ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS[Z/offset])
+      const lastSyncMs = Date.parse(lastSync);
+      if (isNaN(lastSyncMs)) {
+        metrics.errors++;
+        findings.push({
+          severity: 'low',
+          confidence: 0.6,
+          file_path: overviewPath,
+          title: `[vault-staleness] ${slug}: lastSync is not a valid date`,
+          description: `Could not parse lastSync value: "${lastSync}"`,
+          evidence: { slug, tier, lastSync, delta_hours: undefined },
+        });
+        continue;
+      }
+
+      const delta = now - lastSyncMs;
+      if (delta > HOURS_24) {
+        const severity = delta > HOURS_168 ? 'medium' : 'low';
+        const dh = deltaHours(delta);
+        metrics.stale_count++;
+        findings.push({
+          severity,
+          confidence: 0.9,
+          file_path: overviewPath,
+          title: `[vault-staleness] ${slug}: ${formatDelta(delta)} since last sync`,
+          description:
+            `lastSync is ${formatDelta(delta)} old (threshold: 24h). ` +
+            `Note: this compares lastSync age against probe run time, not upstream lastCommit — ` +
+            `a future iteration will add repo-path resolution for a more precise delta.`,
+          evidence: { slug, tier, lastSync, delta_hours: dh },
+        });
+      }
+    }
+
+    const duration_ms = Math.round(Date.now() - start);
+
+    // --- JSONL append (only when we actually scanned) ---
+    const record = {
+      timestamp: new Date().toISOString(),
+      probe: 'vault-staleness',
+      project_root: projectRoot,
+      vault_dir: vaultDir,
+      scanned_projects: metrics.scanned_projects,
+      stale_count: metrics.stale_count,
+      errors: metrics.errors,
+      duration_ms,
+      findings: findings.map(f => ({
+        slug: f.evidence.slug,
+        severity: f.severity,
+        last_sync: f.evidence.lastSync,
+        delta_hours: f.evidence.delta_hours,
+        flag: 'stale-yes',
+      })),
+    };
+    try {
+      mkdirSync(join(projectRoot, '.orchestrator/metrics'), { recursive: true });
+      appendFileSync(
+        join(projectRoot, '.orchestrator/metrics/vault-staleness.jsonl'),
+        JSON.stringify(record) + '\n'
+      );
+    } catch {
+      // JSONL write failure is non-fatal — telemetry append should not discard scan results.
+    }
+
+    return { findings, metrics, duration_ms };
+
+  } catch (err) {
+    return {
+      findings: [{
+        severity: 'medium',
+        confidence: 0.5,
+        title: '[vault-staleness] probe error',
+        description: err.message,
+        evidence: {},
+      }],
+      metrics: { scanned_projects: 0, stale_count: 0, errors: 1 },
+      duration_ms: Math.round(Date.now() - start),
+      error: err.message,
+    };
+  }
+}
+
+export default runProbe;