@limina-labs/momentum 0.30.2

package/core/orchestration/scout.js

@@ -0,0 +1,327 @@
+'use strict';
+
+// scout — read-only single-repo context fetch.
+//
+// Walks the target repo's spec tree + recent history, summarises what
+// it finds relative to the user's prompt, and returns a structured
+// ScoutResult. Cheap-layer side effects: writes a scout-NNN.md run
+// artifact and appends one line to the ecosystem session log.
+//
+// In-process mode (CLI floor): file-system walker only. Returns a
+// summary stitched from file contents — no LLM synthesis available
+// from raw Node.
+//
+// In-agent mode (invoked from a slash command on Claude Code / Codex /
+// Antigravity): the agent does the reading + summarising in its own
+// context (via Task tool or equivalent). The agent then calls back
+// into this library with a structured result to record the artifact +
+// session log line.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const eventsLib = require('./events');
+const runArtifact = require('./run-artifact');
+const sessionLog = require('./session-log');
+const types = require('./types');
+
+const DEFAULT_SCAN_FILES = [
+  'specs/status.md',
+  'specs/backlog/backlog.md',
+  'README.md',
+  'CLAUDE.md',
+  'AGENTS.md',
+  'package.json',
+];
+
+const DEFAULT_SCAN_DIRS = [
+  'specs/architecture',
+  'specs/phases',
+  'specs/decisions',
+];
+
+const MAX_FILE_BYTES = 64 * 1024;
+const MAX_FILES_READ = 30;
+
+/**
+ * Run a scout in-process against the target repo.
+ *
+ * @param {object} opts
+ * @param {string}  opts.repo              absolute path to target repo
+ * @param {string}  opts.prompt            user-provided scope prompt
+ * @param {string}  [opts.originatingRepo] absolute path to invoking repo (defaults to opts.repo)
+ * @param {object}  [opts.adapter]         adapter module (only used for events context)
+ * @param {object}  [opts.emitter]         pre-built event emitter (otherwise a quiet one is created)
+ * @param {object}  [opts.ecosystem]       { rootPath, memberId } — when present, session log is written
+ * @param {boolean} [opts.silent]          suppress default renderer (tests)
+ * @returns {Promise<ScoutResult>}
+ */
+async function scout(opts) {
+  const { repo, prompt } = opts;
+  if (!repo || !prompt) {
+    throw new Error('orchestration/scout: opts.repo and opts.prompt are required');
+  }
+  const originatingRepo = opts.originatingRepo || repo;
+  const start = Date.now();
+
+  const emitter = opts.emitter || eventsLib.createEmitter({ primitive: 'scout', repo });
+  if (!opts.emitter && !opts.silent) {
+    emitter.on(eventsLib.createRenderer({ stream: process.stdout }));
+  }
+  if (opts.ecosystem) {
+    emitter.on(eventsLib.createPersister({
+      ecosystemRoot: opts.ecosystem.rootPath,
+      memberId: opts.ecosystem.memberId,
+    }));
+  }
+
+  emitter.emit('started', { message: prompt });
+
+  const filesRead = [];
+  const sections = [];
+
+  for (const rel of DEFAULT_SCAN_FILES) {
+    const abs = path.join(repo, rel);
+    if (!fs.existsSync(abs)) continue;
+    if (filesRead.length >= MAX_FILES_READ) break;
+    const content = readClampedFile(abs);
+    if (content == null) continue;
+    filesRead.push(rel);
+    emitter.emit('step', { message: `reading ${rel}` });
+    const snippet = extractRelevantSnippet(content, prompt);
+    if (snippet) sections.push({ source: rel, snippet });
+  }
+
+  for (const relDir of DEFAULT_SCAN_DIRS) {
+    if (filesRead.length >= MAX_FILES_READ) break;
+    const absDir = path.join(repo, relDir);
+    if (!fs.existsSync(absDir)) continue;
+    for (const file of listMarkdownFiles(absDir, MAX_FILES_READ - filesRead.length)) {
+      const abs = path.join(absDir, file);
+      const rel = path.join(relDir, file);
+      const content = readClampedFile(abs);
+      if (content == null) continue;
+      filesRead.push(rel);
+      emitter.emit('step', { message: `reading ${rel}` });
+      const snippet = extractRelevantSnippet(content, prompt);
+      if (snippet) sections.push({ source: rel, snippet });
+    }
+  }
+
+  const summary = renderSummary({ repo, prompt, sections });
+  const findings = []; // in-process scout does not infer findings; agent-driven scout adds them via record()
+  const duration = Date.now() - start;
+
+  const { runId, artifactPath } = runArtifact.writeWithAllocatedId({
+    repo: originatingRepo,
+    primitive: 'scout',
+    bodyFor: (id) => renderArtifact({ runId: id, repo, prompt, filesRead, sections, summary, findings, duration }),
+  });
+
+  emitter.context.runId = runId;
+  emitter.emit('finished', { duration, runArtifactPath: artifactPath });
+
+  const result = {
+    repo,
+    prompt,
+    summary,
+    findings,
+    filesRead,
+    duration,
+    runArtifactPath: artifactPath,
+    runId,
+  };
+  return types.validateScoutResult(result);
+}
+
+/**
+ * Record a scout that was performed by an external agent (e.g., a
+ * Claude Code subagent invoked via a slash command). The agent passes
+ * in the result fields; we write the artifact + log line uniformly so
+ * slash + CLI doors produce identical output shape.
+ *
+ * @param {object} opts
+ * @param {string} opts.repo
+ * @param {string} opts.prompt
+ * @param {string} opts.summary
+ * @param {Finding[]} [opts.findings]
+ * @param {string[]} [opts.filesRead]
+ * @param {string} [opts.originatingRepo]
+ * @param {object} [opts.ecosystem]
+ * @param {number} [opts.duration]
+ * @returns {ScoutResult}
+ */
+function record(opts) {
+  const {
+    repo, prompt, summary,
+    findings = [], filesRead = [],
+    originatingRepo = repo,
+    ecosystem,
+    duration = 0,
+  } = opts;
+  if (!repo || !prompt || !summary) {
+    throw new Error('orchestration/scout.record: repo, prompt, summary required');
+  }
+  const { runId, artifactPath } = runArtifact.writeWithAllocatedId({
+    repo: originatingRepo,
+    primitive: 'scout',
+    bodyFor: (id) => renderArtifact({ runId: id, repo, prompt, filesRead, sections: [], summary, findings, duration }),
+  });
+  if (ecosystem && ecosystem.rootPath && ecosystem.memberId) {
+    sessionLog.appendLine({
+      ecosystemRoot: ecosystem.rootPath,
+      memberId: ecosystem.memberId,
+      kind: 'scout',
+      summary: `${repo}: ${prompt}`,
+      context: `run-${runId} → ${path.relative(originatingRepo, artifactPath)}`,
+    });
+  }
+  // Tracking contract: each finding proposed as [DISCOVERY] in the
+  // SCOUTED repo's active phase history when meaningful per Rule 3.
+  // No backlog.md writes — tracking returns a hint the caller can act
+  // on with explicit user confirmation.
+  const tracking = require('./tracking');
+  for (const finding of findings) {
+    tracking.proposeDiscovery({ primitive: 'scout', finding, targetRepo: repo });
+  }
+  const result = {
+    repo, prompt, summary,
+    findings, filesRead,
+    duration,
+    runArtifactPath: artifactPath,
+    runId,
+  };
+  return types.validateScoutResult(result);
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function readClampedFile(abs) {
+  try {
+    const stat = fs.statSync(abs);
+    if (!stat.isFile()) return null;
+    if (stat.size === 0) return '';
+    const buf = Buffer.alloc(Math.min(stat.size, MAX_FILE_BYTES));
+    const fd = fs.openSync(abs, 'r');
+    try {
+      const bytes = fs.readSync(fd, buf, 0, buf.length, 0);
+      return buf.slice(0, bytes).toString('utf8');
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+function listMarkdownFiles(dir, max) {
+  const out = [];
+  function walk(rel) {
+    if (out.length >= max) return;
+    const abs = path.join(dir, rel);
+    let entries = [];
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= max) return;
+      if (e.name.startsWith('.') || e.name.startsWith('_')) continue;
+      const next = rel ? path.join(rel, e.name) : e.name;
+      if (e.isDirectory()) {
+        walk(next);
+      } else if (e.isFile() && /\.md$/.test(e.name)) {
+        out.push(next);
+      }
+    }
+  }
+  walk('');
+  return out;
+}
+
+function extractRelevantSnippet(content, prompt) {
+  const keywords = tokenize(prompt);
+  if (keywords.length === 0) {
+    return clampSnippet(content.split('\n').slice(0, 12).join('\n'));
+  }
+  const lines = content.split('\n');
+  const hits = [];
+  const lower = lines.map((l) => l.toLowerCase());
+  for (let i = 0; i < lines.length; i++) {
+    if (keywords.some((k) => lower[i].includes(k))) {
+      const start = Math.max(0, i - 2);
+      const end = Math.min(lines.length, i + 4);
+      hits.push(lines.slice(start, end).join('\n'));
+      if (hits.length >= 3) break;
+    }
+  }
+  if (hits.length === 0) return null;
+  return clampSnippet(hits.join('\n…\n'));
+}
+
+function tokenize(prompt) {
+  return prompt
+    .toLowerCase()
+    .split(/[^a-z0-9_-]+/i)
+    .filter((w) => w.length >= 3 && !STOPWORDS.has(w));
+}
+
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'this', 'that', 'from', 'are', 'was',
+  'have', 'has', 'will', 'what', 'how', 'why', 'when', 'where', 'shape',
+  'state', 'current', 'status',
+]);
+
+function clampSnippet(s) {
+  if (s.length <= 800) return s;
+  return s.slice(0, 800) + '\n…[truncated]';
+}
+
+function renderSummary({ repo, prompt, sections }) {
+  if (sections.length === 0) {
+    return `No content matching "${prompt}" was found in ${repo}'s spec tree.`;
+  }
+  const head = `Found ${sections.length} relevant section(s) in ${repo} for prompt "${prompt}":`;
+  const bullets = sections.map((s) => `  - ${s.source}`).join('\n');
+  return `${head}\n${bullets}`;
+}
+
+function renderArtifact({ runId, repo, prompt, filesRead, sections, summary, findings, duration }) {
+  const lines = [
+    `# scout-${runId} — ${repo}`,
+    '',
+    `**Prompt:** ${prompt}`,
+    `**Duration:** ${duration}ms`,
+    `**Files read (${filesRead.length}):**`,
+    filesRead.length ? filesRead.map((f) => `  - ${f}`).join('\n') : '  (none)',
+    '',
+    '## Summary',
+    '',
+    summary,
+    '',
+  ];
+  if (findings.length) {
+    lines.push('## Findings', '');
+    for (const f of findings) {
+      lines.push(`- **${f.kind || 'note'}**: ${f.title}`);
+      if (f.detail) lines.push(`  ${f.detail}`);
+    }
+    lines.push('');
+  }
+  if (sections.length) {
+    lines.push('## Sections', '');
+    for (const s of sections) {
+      lines.push(`### ${s.source}`, '', '```', s.snippet, '```', '');
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  scout,
+  record,
+  // exported for tests:
+  extractRelevantSnippet,
+  tokenize,
+};

package/core/orchestration/session-log.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// Shared session-log writer for orchestration primitives.
+//
+// Appends a single line to <ecosystem-root>/sessions/YYYY-MM-DD.md per
+// primitive invocation. Uses the same mkdir-based lock pattern as
+// `core/ecosystem/scripts/session-append.sh` (Phase 10 BUG-004 fix)
+// so we don't race with the PostToolUse hook commits.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCK_BUDGET_MS = 5000;
+const LOCK_POLL_MS = 50;
+
+/**
+ * Append a single event line to today's ecosystem session log.
+ *
+ * @param {object} opts
+ * @param {string} opts.ecosystemRoot   absolute path to ecosystem root
+ * @param {string} opts.memberId        member id of the originating repo
+ * @param {string} opts.kind            event kind, e.g. 'scout' | 'dispatch' | 'handoff'
+ * @param {string} opts.summary         one-line summary (no embedded newlines)
+ * @param {string} [opts.context]       optional context (run id, artifact path, …)
+ * @param {Date}   [opts.now]           override clock for tests
+ * @returns {{ sessionFile: string, line: string, written: boolean }}
+ */
+function appendLine(opts) {
+  const { ecosystemRoot, memberId, kind, summary, context = '', now = new Date() } = opts || {};
+  if (!ecosystemRoot || !memberId || !kind || !summary) {
+    return { sessionFile: '', line: '', written: false };
+  }
+  if (!fs.existsSync(path.join(ecosystemRoot, 'ecosystem.json'))) {
+    return { sessionFile: '', line: '', written: false };
+  }
+
+  const sessionsDir = path.join(ecosystemRoot, 'sessions');
+  fs.mkdirSync(sessionsDir, { recursive: true });
+  const today = isoDate(now);
+  const sessionFile = path.join(sessionsDir, `${today}.md`);
+  const hhmm = isoHourMinute(now);
+
+  const cleanSummary = summary.replace(/\r?\n/g, ' ').trim();
+  const cleanContext = context.replace(/\r?\n/g, ' ').trim();
+  const line = cleanContext
+    ? `${hhmm}Z [${memberId}] ${kind}: ${cleanSummary} (${cleanContext})`
+    : `${hhmm}Z [${memberId}] ${kind}: ${cleanSummary}`;
+
+  const lockDir = `${sessionFile}.lock`;
+  if (!acquireLock(lockDir)) {
+    // Drop event silently rather than corrupt the file. Session events
+    // are advisory; momentum's correctness does not depend on every
+    // line landing.
+    return { sessionFile, line, written: false };
+  }
+
+  try {
+    if (!fs.existsSync(sessionFile)) {
+      const header = [`# Session ${today}`, ''];
+      const activePath = path.join(ecosystemRoot, '.state', 'active-initiative');
+      if (fs.existsSync(activePath)) {
+        const active = fs.readFileSync(activePath, 'utf8').trim();
+        if (active) header.splice(1, 0, `Active initiative: ${active}`);
+      }
+      fs.writeFileSync(sessionFile, header.join('\n') + '\n');
+    }
+    fs.appendFileSync(sessionFile, line + '\n');
+
+    const statePath = path.join(ecosystemRoot, '.state');
+    fs.mkdirSync(statePath, { recursive: true });
+    fs.writeFileSync(path.join(statePath, 'last-session'), today + '\n');
+  } finally {
+    releaseLock(lockDir);
+  }
+
+  return { sessionFile, line, written: true };
+}
+
+function acquireLock(lockDir) {
+  const start = Date.now();
+  while (Date.now() - start < LOCK_BUDGET_MS) {
+    try {
+      fs.mkdirSync(lockDir);
+      return true;
+    } catch (err) {
+      if (err && err.code !== 'EEXIST') throw err;
+      // Busy-wait briefly. Acceptable here — the lock holder is on the
+      // same machine and releases within milliseconds in practice.
+      sleepSync(LOCK_POLL_MS);
+    }
+  }
+  return false;
+}
+
+function releaseLock(lockDir) {
+  try {
+    fs.rmdirSync(lockDir);
+  } catch {
+    // Lock directory may have already been released or never acquired.
+  }
+}
+
+function sleepSync(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    // intentional spin — only used briefly during lock contention
+  }
+}
+
+function isoDate(d) {
+  return d.toISOString().slice(0, 10);
+}
+
+function isoHourMinute(d) {
+  return d.toISOString().slice(11, 16);
+}
+
+module.exports = {
+  appendLine,
+  // Exported for tests:
+  acquireLock,
+  releaseLock,
+};

package/core/orchestration/tracking.js

@@ -0,0 +1,180 @@
+'use strict';
+
+// tracking — meaningful-only writes to curated docs (history.md / backlog.md).
+//
+// Cheap layer (session log + run artifact + handoff inbox) is auto-
+// written by the individual primitives. This module handles the
+// curated layer:
+//
+//   - proposeDiscovery({ primitive, finding, targetRepo })
+//     Applies Rule 3 criteria (real bug, real tech debt, real
+//     enhancement). If meaningful, appends a [DISCOVERY] entry to
+//     the target repo's active phase history. Otherwise no-op.
+//
+//   - proposeHistoryNote({ primitive, originatingRepo, message,
+//                          runArtifactRef })
+//     For dispatch synthesis or other meaningful cross-repo notes.
+//     Appends a [NOTE] in originating repo's active phase history.
+//
+// Hard invariants:
+//   - NO new entry types. Reuses [DISCOVERY] / [DECISION] / [NOTE].
+//   - NO writes to backlog.md without explicit user confirmation.
+//     We propose entries; caller decides whether to materialise them.
+//   - Empty/whitespace findings never make it through.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const handoffLib = require('./handoff');
+
+const VALID_BACKLOG_PRIORITIES = new Set(['P0', 'P1', 'P2', 'P3']);
+const VALID_BACKLOG_TYPES = new Set(['bug', 'tech-debt', 'enhancement', 'feature']);
+
+/**
+ * Decide whether a Finding warrants a [DISCOVERY] entry in the target
+ * repo's active phase history.
+ *
+ * @param {object} opts
+ * @param {string} opts.primitive       'scout' | 'dispatch'
+ * @param {Finding} opts.finding
+ * @param {string} opts.targetRepo      where the finding was observed
+ * @returns {{
+ *   shouldWrite: boolean,
+ *   reason: string,
+ *   historyEntry?: string,
+ *   historyPath?: string,
+ * }}
+ */
+function proposeDiscovery(opts) {
+  const { primitive, finding, targetRepo } = opts;
+  if (!finding || typeof finding !== 'object') {
+    return { shouldWrite: false, reason: 'no finding provided' };
+  }
+  if (!finding.title || typeof finding.title !== 'string' || !finding.title.trim()) {
+    return { shouldWrite: false, reason: 'finding has no title' };
+  }
+  // Rule 3 thresholds — must look like a real backlog candidate.
+  if (
+    !VALID_BACKLOG_TYPES.has(finding.recommendedBacklogType) &&
+    !VALID_BACKLOG_PRIORITIES.has(finding.recommendedBacklogPriority)
+  ) {
+    return {
+      shouldWrite: false,
+      reason: 'finding does not declare a recommendedBacklogType or recommendedBacklogPriority — not meaningful per Rule 3',
+    };
+  }
+
+  const activePhase = handoffLib.detectActivePhase(targetRepo);
+  if (!activePhase) {
+    return { shouldWrite: false, reason: 'target repo has no active phase to log into' };
+  }
+
+  const historyPath = path.join(targetRepo, 'specs', 'phases', activePhase, 'history.md');
+  if (!fs.existsSync(historyPath)) {
+    return { shouldWrite: false, reason: `history.md missing at ${historyPath}` };
+  }
+
+  const date = new Date().toISOString().slice(0, 10);
+  const topics = ['orchestration', primitive, 'discovery'];
+  if (finding.recommendedBacklogType) topics.push(finding.recommendedBacklogType);
+
+  const entry = [
+    '',
+    `### [DISCOVERY] ${date} — ${finding.title}`,
+    `Topics: ${topics.join(', ')}`,
+    `Affects-phases: ${activePhase}`,
+    `Affects-specs: ${(finding.filesTouched || []).join(', ') || 'none'}`,
+    `Detail: ${finding.detail || finding.title}${formatBacklogHint(finding)}`,
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  fs.appendFileSync(historyPath, entry);
+  return {
+    shouldWrite: true,
+    reason: 'meaningful per Rule 3',
+    historyEntry: entry,
+    historyPath,
+  };
+}
+
+/**
+ * Append a [NOTE] entry in the originating repo's active phase history.
+ *
+ * Used for dispatch synthesis and any other cross-repo orchestration
+ * note worth a future reader's time. Does NOT use a new entry type.
+ *
+ * @param {object} opts
+ * @param {string} opts.primitive
+ * @param {string} opts.originatingRepo
+ * @param {string} opts.message            one-line description
+ * @param {string} [opts.runArtifactRef]   relative path to .momentum/runs/<primitive>-NNN.md
+ * @returns {{ shouldWrite: boolean, reason: string, historyEntry?: string, historyPath?: string }}
+ */
+function proposeHistoryNote(opts) {
+  const { primitive, originatingRepo, message, runArtifactRef } = opts;
+  if (!message || typeof message !== 'string' || !message.trim()) {
+    return { shouldWrite: false, reason: 'empty message' };
+  }
+
+  const activePhase = handoffLib.detectActivePhase(originatingRepo);
+  if (!activePhase) {
+    return { shouldWrite: false, reason: 'originating repo has no active phase' };
+  }
+
+  const historyPath = path.join(originatingRepo, 'specs', 'phases', activePhase, 'history.md');
+  if (!fs.existsSync(historyPath)) {
+    return { shouldWrite: false, reason: `history.md missing at ${historyPath}` };
+  }
+
+  const date = new Date().toISOString().slice(0, 10);
+  const entry = [
+    '',
+    `### [NOTE] ${date} — ${primitive} synthesis`,
+    `Topics: orchestration, ${primitive}, synthesis`,
+    `Affects-phases: ${activePhase}`,
+    `Affects-specs: ${runArtifactRef || 'none'}`,
+    `Detail: ${message}`,
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  fs.appendFileSync(historyPath, entry);
+  return {
+    shouldWrite: true,
+    reason: 'meaningful synthesis',
+    historyEntry: entry,
+    historyPath,
+  };
+}
+
+/**
+ * Helper: would this finding pass the Rule 3 threshold? Used by tests
+ * and orchestrator code that wants to decide BEFORE proposing.
+ */
+function isMeaningfulFinding(finding) {
+  if (!finding || typeof finding !== 'object') return false;
+  if (!finding.title || !finding.title.trim()) return false;
+  return (
+    VALID_BACKLOG_TYPES.has(finding.recommendedBacklogType) ||
+    VALID_BACKLOG_PRIORITIES.has(finding.recommendedBacklogPriority)
+  );
+}
+
+function formatBacklogHint(finding) {
+  const parts = [];
+  if (finding.recommendedBacklogType) parts.push(finding.recommendedBacklogType);
+  if (finding.recommendedBacklogPriority) parts.push(finding.recommendedBacklogPriority);
+  if (parts.length === 0) return '';
+  return ` (backlog candidate: ${parts.join(' / ')})`;
+}
+
+module.exports = {
+  proposeDiscovery,
+  proposeHistoryNote,
+  isMeaningfulFinding,
+  VALID_BACKLOG_PRIORITIES,
+  VALID_BACKLOG_TYPES,
+};